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ABSTRACT 


Problems associated with the production and operational 
Support of DoD weapon system software are exarined. Emphasis 
Mmemplaced on identifying técnriacues that are currently 
available for improving the maintainability of this 
software. A discussion of the software je cycle, 
structured programming methodologies, use of high order 
languages, and documentation recuirements for software is 
included with a review of anvplicable DoD policies. Amorg the 
eenclusions is that there exists a critical need to 
mecorznize Maintainability as a primary design obdjective for 


DoD weapon system software. 
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T. INTRODUCTION 


A. NEED FOR IMPROVED SOFTWARE MAINTENANCE 

On 9 Novemder 1979 the North American Air Defense 
Command Headquarters in Colorado received an alert of a 
Soviet missile attack [1]. Fortunately, within 6 minutes it 
was determined to be an apparent computer malfunction but 
moe, verorme i28 U.S. and Canadian intercevtors took off from 
Baerr DvaseS.ewhile not trizzerine th2 nuclear holocaust that 
looms over the modern world, such an event at least shatters 
the confidence cf many individuals in Department of Defense 
(DoD) computer systems. 

Articles, such as the one anpearing in the San Francisco 
Sundey Examiner [2], which highlight a wide variety of large 
Scale, expensive DoD computer system failures and refer to 
Federal Computer Systems as a multi-billion-dollar 
quagrire do little to convince the public that LoD 
personnel are capable Ot designing, developing or 
maintaining complex computer systems. 

Ample examples illustrate that software in DoD comouter 
Systems is the mein culprit behind these hignly visible 
failures. Since it appears unlikely that complex, weapon 
System software will be produced error-free in the 
foreseeable future, the maintenance of this software takes 


eceaecritically importert role. 





Besides the ramifications that non-maintainadle software 
brings, the cost associated with the software life cycle is 
cause for increasinaly serious corcern. In fact, a Defense 
Science Board Task Force on Technology Base Strategy (3), 
composed of members from industry, medicine, goverrment and 
universities, concluded that the cost of software has becore 
aaemational problem and is of particular concern to DoD. 

When costs associated with weapon system scftware are 
more closely analyzed, it is found that maintenance 
activities account for a large percentage. The Rome Air 
Development Center gives the figure of up to seventy percerct 
{4}. Actual projects can be used for illustration. For 
instance, SAGE, a military defense system, had an average 
software meintenanee cost of approximately 2a ‘mililon 
memrars per year after 10 years of operation, comvared to an 
initial development cost of 2523 rillion dollars [5]. De Roze 
[6] explains that Air Force Avionics software costs around 
Sra per instruction to develop, but the maintenance for this 
software cests around $4,0@¢@ per instruction. 

These large percentages for software mainterence costs 
can be confirmed by examples from industry. Mills [7] points 
out in only 25 years 75 percent of data processing 
personnel - are aiready taken und with maintenance, not 
developmert. On the IBM operating system, I3M 26@ OS, 
approximately Pour times as much time was spent on 


Maintenance as on development [8]. Boehm [9] reports that a 








recent analysis of software activities at General Motors 
indicated that about 75 percent of GM’s Software effort goes 
mmno maintenance, and that GM is fairly typical in this 
resvect of industry at large. 

There are indications that maintenance problems are 
compounded for real-time system software. Daly [121, for 
example, found that programmers were able to maintain only 
one-fourth to one-third as many instructions of on-line, 
real-time programs as other tyve software. 

The study of software maintenance becomes so important 
because of the need to keen Dold real-time, weapon system 
software operating as error-free as possible and the need to 
check the escalating cost associated with modifying this 
software that the study of software mainterarce becomes so 
imvortant. 

The software associated with the U. S. Navy’s new 
TRIDENT class submarine, known as the TRIDENT Cormrand and 
Control System (TRILTENT CCS), is a current, real-time weapon 
system software project that provides an interesting and 
beneficial example for illustrating the need for weanon 
system software Maintenance activitiss. 

The original source code was written in the Navy's high 
order language (HOL), CMS-2. Ever though this code was 
generated by highly experienced software ergineers and, 
according to Oxman [11], was of a very high caliber and 


quality, the maintainability of the CCS software nas becore 
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emer orOr COnCeroae ec part, this is a4 résult of the way 
software errors found during the integration test and 
evaluation stages were corrected. Logic fixes were applied 
directly via the object code rather than by using the source 
code. Now the TRIDENT CCS kas over thirty-five thousand 
Mommas Of OOject level only code. An effort is currently 


underway to improve the maintainability of the TRIDENT CCS. 


PeeeeURPOSE AND APPROACH 

The purpose of this thesis is to evaluate available 
maintenance techniques that are appvlicable for use with DoD 
weapon system software such as the TRIDENT CCS. This 
Evaluation is based upon the currert state of the art as 
Meeceussed in the technical literature and existing PoP 
policies. Where possible, actual TRIDENT CCS software has 
been used to provide a realistic exerple for comparing 


various maintenance te2chniuaues. 


ia 


he approach used will be to presért in the nrext 
eiapver, Chapter [1I, a discussion of the overall software 
life cycle illustrating the relationship maintenance has to 
the various life cycle phases. Software life cycle 
Managemert methodologies useful for obtaining improved 
software maintainability will be ircorporated, such as the 
use of design reviews and configuration management. Some 
Seenificant differences between software and hardware 


eeguisition will also be included. 


1G 








Chapter II] covers the techniques that must %e applied 
during the development nhase of the software life cycle, for 
Soeainineg more Maintainable software, specifically, the use 
of structured programming methodologies, use of high order 
languages, and automated aids. 

fraover ee iy addresses the important issue of softwars 
documentation. A full set of applicable Dol documents used 
mommmesuDppoOrt the mainterance of weapon system software is 
identified. Emphasis, however, iS placed on corparing those 
techniques that are currently available for representing the 
program logic to the maintenance programmer: flowcharts, 
hierarchy plus ipout-process—out put (HIPO) diagrams, 
decision tables, Nassi~-Shneiderman charts, and prograr 
ieestings. 

Chapter VY concerns specific software maintenance 
moe ies)6«6©Within DoD. This includes an identification of the 
eomrent, directives, instructions, and standards that impact 
On weapon system software maintenance; the results from a 
limited survey of some DoD organizations that are involved 
in software maintenance activities; and trends that exist 
for research in tne area of software maintenance technology. 

Finally, Chapter VI contains conclusions and 


recommendations. 


We 








C. DEFINITIONS 

Pefore any further discussion, exactly what is meant by 
the term software maintainability shouli be made clear. 
Mnreortunately, there is no universally accepted definition; 
therefore, some perceptions from various authors will be 
Dreesertec. 

Myers [5] lists maintainability as one of ten major 
catezories of software objectives: generality, human 
Pactors, adaptability, Maintainability, SCCUrILY, 
meocurentation, product cost, schedule, ee ielency and 
Peliability. It is important to understand the relationships 
among these categories so that appropriate tradeoffs can de 
made during the process of software development. Ee explains 
that maintainability and adaptability are closely related 
and that both are compatible with obtaining software 
reliability. The definition presented for ‘maintainability’ 
is that it is a measure of th® cost and time required to 
fix software errors in an operational system. The 
@ssociated term, adaptability , is defined as a measure 
for the ease of extending the product, such as adding new 
user functions to the vroduct. 

More formalized definitions are offered by Tausworthe 
2] : 

Maintenance: alterations to software during the vost 

demivery periog in the form of sustaining engineering or 


Od taeda c LON not EcouULrIMCmmd rel nt tiation of the 
Software development cycle. 
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Sustaining Engineering: Software related activities in 
the post-delivery period, principally supportive in 
form, which keep that software operational within its 
mumctiOnali svuecifications. . . Tne holding or keevine of 
software in a state of efficiency or validity desvite 
interface PiuUetwat 1Ons in system, subsystem OP 
applications capabilities. 


Micomeauion: Modification of Existing softwere in order 
that it may be used as a module in é program 
developmert, as opposed to developing another module for 
that same purpose. 

Modification: The vrocess of altering a program and its 
specification so as to perform either anew task or a 


qifferent but similar task. In all cases, the functional 
scope of a program under modification changes. 


igure 1-1 [13] is a chart that brings rany of these 
Similar terms together as they are related to the more 
memera: concept of software quality. It itllustrates what 
attributes are associated with each of three factors of 
software quality (operation, revision, and transition). 


morace that maintainability is listed as an attribute 


mesoociate€d with product revisior. 









MAINTAINABILITY - PORTABILITY - WILL I BE ABLE TO USE IT 
CAN I FIX IT? ON ANOTHER MACHINE? 
FLEXIBILITY - REUSABILITY - WILL I BE ABLE TO REUSE 
CAN I CHANGE IT? SOME OF THE SOFTWARE? 


INTEROPERABILITY - WILL I BE ABLE TO 
INTERFACE IT WITH 
ANOTHER SYSTEM? 


TESTABILITY - 
CAN I TEST IT? 





PROCUCT OPERATIONS 


CORRECTNESS - DOES IT DO WHAT I WANT? EFFECIENCY - WILL IT RUN ON MY HAROWARE AS 


4 ? 
RELIABILITY - OOES IT DO IT ACCURATELY ALL THE TIME? @ELL AS IT oe 
USABILITY - CAN I RUN IT? INTEGRITY - IS IT SECURE? 


Pigure 1-1. Software Quality [13] 
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Yet another attempt to provide a relationship among the 
various factors in quality software is given in Figure 1-2 
[14]. The factors are categorized into two classes: (1) 
measurement of what is quality ard (2) control over software 
production to ensures that quality 15 obtained. Note that 
Maintenance fells under flexibility which in turn falls 


under the measurement of what is quality. 


ie 





[nt] eexz exengzog AyTTeNd ous, *2-] eanFty 
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Swanson [15] has attempted to provide a basis for an 
understanding of the dimensionality of the maintenance 
problem. He feels it is important to distinguish between 
types of software maintenance activities. F&@ categorizes 
Maintenance into three major types: corrective maintenance, 
adaptive maintenance, and perfective maintenance. Corrective 
Maintenance is performed in response to failures such as the 
abnormel termination of a vrogram or the failure in meetinz 
performance criteria. Adaptive maintenance is performed in 
response to changes in ervironments such as the installation 
of a new generation of system nardware. Perfective 
maintenance is performed to make the program amore perfect 
design imolementation such as to improve processing 
Srticiency or to add new features. 

It is interesting to note that there are vroponents for 
drooping the terminology “software maintenance altogether. 
The FDP Analyzer [16] suggests a better name for 
“maintenance. type activities would de “oreduction 
programming. The contention being this would helv alleviate 


the stigma that maintenance is technician level rather than 


professional level work. Kline {17 ] areues that 
misconcentions about software reliability and 
maintainability have been, to some extent, due to 


feragppropriate terminology. In order to minimize confusion 


with hardware maintainability, he suegests replacing the 


i 





term software maintainability with the more descriptive 
term “software configuration management. 

(ters evident that mo stardard terminology exists for 
this area. Rather than oursue the search for even more 
Merimitions it will simply be stated that software 
maintainability, as used in this thesis, will refer to the 
degree a software oreduct facilitates undating to satisfy 
new requirements COneOGItreaynon — FO GOrrect mistakes 
(adapted from [4]). 

item wOolS and techriaues that currenthy exist for 
producing more maintainable software re addressed next. 
Throughout the remaining chapters it shoulce be kert in mind 
that, while specifically addressing software raintenance, 
the principles presented are generally applicable to the 
many other nuances of successfully accommodating changes to 
software (°e.g., portability, flexibility, adavtability). 

Also, it is extremely important to be aware that there 
are a variety of parameters which can be used tc measure the 
Maelity of a software product, as the previous discussion 
has illustrated. An attempt to optimize one parameter is 
Orten at the expense of other parameters. For example, 
optimizing the maintainability of software may be at the 
expense of déevelocvment schedule or, conversely, and what 
appears to have been a common pitfall of past projects, to 
optimize development schedule may be at the expense of 


Subsequent maintainability. These opposing objectives must 
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be understood and appreciated by all levels of managerert 


before tradeoff decisions are made. 


1S, 





Lee JoseoOr Iwas LISE CYCLE 


A. SOFTWARE LIFE CYCLE MODELS 

The first step in studylne techniaues associated with 
maintainability of weapon system software is to examine all 
the phases through which scftware transitions prior to and 
Mmecruding the operational point where maintenance is 
merrormed. This is commonly called the software life cycle. 
tee as important that this is understood, because the 
decisions made throughout the earlier phases will ultimately 
affect the software’s maintainability. Unfortunately, as 
opposed to hardware, there is no universal agreement on the 
phases Of tae set tware life cycle, with well-defined 
Boundaries, so several models will be discussed in order to 
provide a broader understanding. 

The first software life cycle model discussed will be 
one proposed by Manley [18]. This model is only aie slight 
modification of the already well-understood DoD system life 
cycle, as presented in DOD INST 5300.1, and as shown in 
eryeure 2-1. 

One advantage of USinor Ch Seetmode! 1S that the 
terminology appearing in existing DoD documents need not be 
replaced but simply modified. A disadvantage is that it does 
little to illustrate the interrelationships that exist among 


the various phases. 
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An interesting conclusion reached in Manley’s report is 
that one software life cycle model applies equally to all 
types of software. This includes both weapon system software 
as well as automated data processing software. The report 
recommends that further research be conducted in order to 
add conceptual detail to the individual life cycle subphases 
and further recommends that research efforts should be 
concentrated on the support phase where maintenance is 


performed. 
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Figure 2-1. Software Life Cycle Model [18] 
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Brown (19] provides a good contrast of two views of the 
software life cycle. Ore view as a fixed sequence of the 
following events and the other, more accurate view, as a 
SompLlex and highiy dynamic intfractior of the following 
events (see Figure 2-2): 


Concept ( Requirements ) Definition 
Detailed Reauirements Specification 
Preliminary Design 
Detailed Design 
Code and Debdug 
Checkout 
Test plarnnizeg 
Test execution 
Test evaluation 
- Acceptance and Use 
. Maintenance (Modification) and Re-test 


Pre OMOND OP Ome 


> © o 


While Figure 2-2 represents the interrelationshios among 
moe poeases of the software life cycle, it overly sirvlifies 
the importance of the maintenance phase (node 11). This 
bottom loon really illustrates what should de considered as 
a mini-life cycle which would include many of the same 


memes and interreletionships shown by the previous nodes. 
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Figure 2-2. “Sequential” View and a “More Accurate’ Yiew 
of Software Production [19] 
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McHenry [(2@] describes weapon system software life cycle 
management from a contractor’s verspective. He states that 
today’s procurement processes still use the traditional life 
cycle model consisting of the sequential stevs of ‘define, 
design, develop, integrate, test, and operate. After 
evaluating four different procurement strategies being used 
for the procurement of weapon system software tcday, he 
concludes that this is not a satisfactory way to envision or 
to manage] the software development process. The deployment 
and operation phases of the software life cycle, where 
maintenance becomes a key issue, are said to de often 
overlooked or neglected because of the pressures ard crises 
which occur during the develovment phases. To compound this 
problem, there is a tendency to apply low skill persors to 
“maintenance tasks. 

Fe recommends more emphasis be placed on software design 
so that the product is less costly to maintain and advocates 
the use of, what he terms, readiness management (planning 
for change) by doing such things as conducting exercises 
where simulated modifications occur. 

The software life cyclé model described by the Rome Air 
Development Center [4] seems to accurately model the 


software life cycle (Figure 2-3). 
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Figure 2-3. Software Life Cycle [4] 
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Figure 2-3 shows that the process of software 
development is highly interactive, as indicated by the 
feedback arrows to accommodate new software reauirements and 
emanees to software specifications. More significantly. it 
highlights the importance of the operation and support phase 
where maintenance 1s performed through a series of 
subphases. Note that these subphases incorporate the seme 
Mmreractive steps shown for software development: softwere 
analysis, software design, coding and checkout, and test and 
integration. 

A variety of models have deen presented in an effort to 
better understand how maintenance relates to the overall 
software life cycle. It must be emphasized that even though 
maintenance appears chronologically last it must be properly 
Considered and thoroughly planned for early in the life 
cycle. 

BeeANAGING THE SOFTWARE LIFE CYCLE 
1. General 

Now that a conceptual framework has been presented 
mor Envisioning the life cycle of software and highlighting 
the importance of the phase where maintenance is performed, 
attention is turned to software management considerations. 
This is important because the decisicns made by managers of 
Peapon system software projects will often mean the 
difference between whether the final product is maintainable 


or noOn-maintainable. 
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There has been some argumert that regardless of what 
Management techniques are employed, successful developrent 
of large, complex software projects is not always possible. 
For example, an Air Force assessment [21] of why its large, 
complex computer system, the Advanced Logistics System 
(ALS), failed concluded that §...the ALS is beyond the 
software state-of-the-art... 

This view is contrasted to one offered by Cave [22]. 
In an article which describes project management methods 
Mmoea 1Or controllirge the life cycle of large-scale software 
systems, he states  ©...project failures are generally the 
result of improper or inexperienced management and not the 
lack of technical ability. The article goes on to conclude 
that successful development of large software systems can be 
achieved in a consistent manner. 

This thesis is based on the premise that Cave’s view 
Memcorrect. It further assumes that software mairtéenance 
problems can be largely avoided if knowledgeabl= praject 
management is applied. 

Cooper [23] explains that, in the past, one of the 
common pitfalls in project management has been that it was 
development-oriented and, therefore, management attempted to 
optimize the development process in trying to meet budget 
Pease scuedule constraints. This tends to create an initial 


design with little documentation, resulting in increéesed 
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difficulty in maintaining the software and a corresponding 
increase in overall 11f8 cycle costs. 

Another problem with management ’s abdility to produce 
maintainable software identified by Cooper was that high 
level decision makers lack computer-related experierce. 
al S > undoubtedly, results from the fact that, as a 
aiescrpline, software management is stili in its infancy. 

While there is no simple series of steps for 
managers to follow which will ensure successful development 
of maintainable software, experience has revealed sore 
general policies that appear to help. For example, Daly [19] 
has reported on his experience in managing developrents. 
ioe Li=g-l provides a comparison of two approaches. Method 1 
is the preferred approach to producing a rore 
cost-effective, more maintainable software product. Note 
that he recommends the application of strict maragement 


meyeetives to guide development. 
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Table IJI~-1. 


Method 1 
High level language 
Sercuctured Code 


Composite design (hierarchy 
of small segments) 


Marailel, top-down, bottom 
up design all optionally 
used 


Simple data structures and 
work areas (not) tightly 
packed 


Team approach to design 
(egoless programming) 


IMB’s structured walk 
through for reviewing 
detail design and code 


Three separate teams 
one team design, one 
tests one evaluates 


Complete set of hierarchy 
charts, sequence charts 
data maps and narratives, 
well commented listings 


Detailed test plans for all 
test phases 


Program maintained by 222 
senior programmers 


Only commercial documenta- 
tion generated during 
development 


Strict management 
objectives established 
to guide developmert 


Zo 


Software Design Methods [12] 


Method e 
Assembly language 
Tight Complex Code 


Large blobs of code 


Bottom-up design 


Teen t wert) Clent. dated 
structures and work areas 
(every bit used, ro data 
duplicated) 


One program ~ One man 
concept 


No detailed technical 
review of design or code 


Original coder tests, 
integrates and helps 
evaluate his ctrogram 


Detailed flow charts and 
geereral narretives, 

no consistency listing 
comments 


No formal test plans 
Program maintained by 
inexperienced cvrogrammers 
or technicians 

Extensive, noncommercial 
technical remorandum gener- 


ateawand placed in ilbprary 


No management objectives 








Peligusyaneasement FOLi cles 


Within DoD the need for improving weapon system 
software managemert has been recognized and action has pbeen 
initiated. On 3 December i974 a DoD Software Steering 
Committee was establishea with a charter to identify 
critical weapon system software problems and to recommend 
Bemmecles for their solution. 

In support of the first phase, the MITRE Corporation 
in conjuction with The Applied Physics Laboratory of Johns 
Hopkins University (24, 25], conducted a study of weapon 
system software management. The study concluded ‘The major 
contributing factor to weapon system problems is the lack of 
discipline and engineering rigor applied to the weapons 
system acquisiticn activities. 

Incorporating recommendations from this study, the 
Software Mane gement Steering Committee formulated a 
@emereaensive plan comprising policy, opractice, procedure 
and technology initiatives. This plan was released in March 
1976 and is available through the Defense Technd cal 
Information Center [26]. Part III of this plan recommends 
femeecemert policy with the purpose of Supplementing 
Principles put forth in DoD Directives 5300.1 and 5099.2. 
The first management policy listed states, "Base of 
maintenance and modification will be a major consideration 


in the initial design. 
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iieepOlectesmoroviged in this plan have the effect 
of establishing visibility and management cortrol to weapon 
system software. Two important techniques used to rrovide 
visibility and management control are design reviews ard 
configuration Management. 

a. Design Reviews 

MIL-STD-1521 (USAF) prescribes the requirements 
for the conduct of the following technical reviews and 
audits on computer programs: 

Systems Requirements Review (SRF) 
System Design Review (SDR) 
Preliminary Design Review (PDR) 
Critical Design Review (CDR) 
Functional Configuration Audit (FCA} 
Physical Configuration Audit (PCA) 
Formal Qualification Review (FQP) 

For detailed Cerin .ons and Soc nue 
Mmeemremerts for these reviews the reader is referred to tne 
Standard. It should be noted that the standard falls to list 
requirements to be specifically considered for optimizing 
the maintainability of the software. An available software 
Maintenance guidebook [27] does, however, provide asa 
supplement to MIL-STD-1521, checklists of maintenence 
considerations for use with the various reviews and audits. 

bd. Configuration Management 

The elements of software Gontdeunrat lon 
Management are configuration identification, configuration 


control, configuration status accounting and configuration 


auditing. Configuration identification involves specifically 
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Mmoeemtir ying and labeling the configuration items at selecte2 
baselines during the software life cycle. Ccenfiguration 
control provides the means to manage changes to tne 
(software) configuration items and involves three basic 
ingredients: 

-~Documentation (such as administrative forms anda 
supporting technical and administrative material) for 
forrally precipitating and defining a vroposed change to 
a software system. 

“An organizational bocy for formally evaluating and 
approving or disapproving a obroposed change to a 
software system. 


seroceaures for controlling the actual changes toa 
software system 


Software configuration status accounting provides tne 
mechanism for maintaining a record of how the software 
evolved and where the software is at any current stage of 
miorementation. software configuration auditing prevides a 
means to determine how well the software product matches its 
associated documentation. 

DoD Directive 5800.29, Management of Comvouter 
Resources in Major Defense Systems, states: 

Defense system computer resources, including both 
computer hardware and computer software Wea Lah oe 
specified and treated as configuration items. 

As part of the proposed requirements assigned to 
contractors for the development of weapon system software, 
MIL-STD-1679, Weapon System Software Development, states: 

The contractor shall establisn and implement the 


disciplines of configuration management, namely 
Comotetratton L1aerntification, configuration control, and 
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Gontveuration status eccounting. The contractcr shall te 
cognizant of the requiremert for long-term life-cycle 
Support of the weapon system software. The appropriate 
degree of configuration management shall be applied to 
ensure completely accurate correlation between 
descriptive documentation and the program in order. to 
facilitate vost-delivery maintenance by software support 
personnel. 

MIL-STD-52779(AD), Software Quality Assurance 
fEoeram Requirements, further requires that the contractor 
provide audits by independent personnel to ensure that the 
objectives of the configuration control program are  deing 
attained. 

This need for software configuration management, 
as reflected in current standards and directives, has deer 
Smeey recently recognized in DoD. Fortunately, it is now 
accepted as an essential task if software mairtenance is to 
be successfully performed. In fact, aS previously mentiored, 
Kline ia proposes replacing the term software 
maintenance with the term “software configuration 
management. This highlights the central role it plays in 
the maintenance of software. 

As Bersoff [28] points out, the vrodlem with 
configuration management of software in the past has been 
that it fell under the umbrella of configuration management 
of the entire system (Figure 2-4). Hardware, being more 
visible, has been treated in great detail, but software, 


being less mature as well as less visible from ae total 


system viewvoint, has been largely neglected. 
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Figure 2-4. Configuration Management Umbrella [28] 


54 





TnerPcweseprOvaDlLy no aspect more important to 
software maintenance than Managing change since software 
maintenance is really a matter of correctly applying 
changes. Clearly, software configuration management must be 
applied to discipline this process. Reew OT, Or wCauc. On. 
however, is that the same change control proececures do not 
apply equally 13.0) all softwere projects; therefore, 
configuration management must be properly tailcred to the 
organization performing Maintenance and to the softwere 
mroauct itself. 

Jc. Software vs Hardware 

The theme pervading the evolving initiatives for 
managing software is to eélevate it from an artistic 
memerorise tO a true engineering discipline, or--to put it 
another way--to treat software more like hardware througnout 
its complete life cycle [1@, 22, 29]. There are, however, 
Serrerences between software and hardware that Merit 
monsiaeratior. 

A ra jor difference is in the maintenance 
requirements. Eardware is maintained primarily by 
replacement of worn or failed components with new ones 
meeting the original specification. Software, unlike 
hardware, requires that the product specification and design 
be changed when maintenance is performed [2@]. 

Among the differences Schneidewind [3@] has pointed 


out are: (1) the passage of time is an important parameter 
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TIT. DEVELOPMENT ISSUES FOR IMPROVED MAINTENANCE 


A. GENERAL 

As mentioned in chapter II, decisions made during the 
development phases of the software life cycle will have a 
Significant impact on how maintainable the software is 
during its operational phase. There is little disagreement 
on the observation made by Mills (7] that better development 
mmeeeaures can reduce the need for maintenance. This chapter 
is concerned with briefly discussing those better 


development procedures. 


B. STRUCTURED PROGRAMMING 

Structured programming is becoming one of the more 
promising approaches to reducing the ever increasing cost of 
producing and maintaining scftware. Meyers [5] states that 
Steuctured programming will probably be recorded in history 
as one of the great steps forward in programming téchnology. 

The Naval Surface Weapons Center [1] and The Naval Air 
Development Center [G2] are two Navy R & [T centers that have 
obtained successful results in producing improved oauality 
weapon system software by using structured orcgremming 
pechriques. 

MmEOressOnmen. = 4. Dijkstra, of the Uaiversiry OL 


Eindhoven, Netherlands, is credited with veing one of the 
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feest £O advocate structured programming principles with his 
1965 paper (33]. Since 1965, many vdooks have deen published 
covering the topic of structured programming [5, 24, @5, 36, 
37, 38, <9]. A complete review of these works will not be 
attempted here, but the following selected items provide a 
general overview. 

As with the term “software maintenance , ro specific, 
widely accepted definition exists for “structured 
programming. Jensen [48] surveys many definitiozs and 
concludes that one proposed by Wirth [41] is the most 
accurate: Structured programming is the formulation of 
programs as hierarchical, nested structures of statements 
and objects of computation. Meyers [5] gives his favorite 
definition of structured programming as the attitude of 
Writing code with the intent of communicating with veople 
instead of machines. 

A goal of structured oprograrming is to organize and 
discipline the program design and coding process in order to 
reduce logic type errors Feape Three importent 
emapacterisitcs of structmred pregramming will serve as the 
framework for further explanation: top-down design, moduler 
design, and structured coding. 

1. Top-down Design 

One characteristic of structured programming is the 
use of top-down design. In a very general sense, this 


Involves first specifying a program in the broedest termrs 
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and ina sten-wise fashion gradually refining the structure 
Moertilil in details. At Gach step, major functions to be 
accomplished are identified, a given task is broken into a 
number of subtasks until the subdtasks are simple enough to 
be coded into modules. If a module requires rore than a line 
feeeeonoOrt Daragraph to describe, then the module should de 
redefined. 

The rationale behind this approach is thet the mind 
1s capable of comprehending only so much at a time and most 
problems are too large to be attacked all at once. 

Top-down design is illustrated in Figure 3-1 [27] 
where successive levels of design provide additional details 
of the eventual solution. This approach will provide 
feect D1 lity to the design which is an important need of the 
maintenance programmer. 

Top-down development has been described as pérhaps 
the least appreciated area of modern software technology 
[42] and includes much mor2 than the simplified descrintion 
Masco pres@€nted. It is a rich and powerful techricue for 
project implementation and for system integration. 

It is interesting to rote that an adaptation of tne 
top-down approach, conceived by O’Neill in 1972, was used 
more the TRIDENT CCS (42, 43, 44]. This was the first time a 
top-down design was specified for use on a Navy weapon 


system software development project [25]. 
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Figure 3-1. Top-down Design [27] 
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2. ,H00ular Design 

Another characteristic of structured programming is 
modular design. A good descrintion of principles and 
practices for module design is provided by Meyers [5]. The 
first step, Meyers explains, in designing a module is 
Befining its external characteristics. This is information 
needed by interfacing rodules, nothing more, and includes: 
module name, function, parameter list, inputs, outputs, and 
external effects. It is recommerded that this information oe 
located in comment statements at the beginning of the source 
code. Only after defining the modules exterral 
characteristics, is design and coding of the internal logic 
accomplished. 

No hard and fast rules exist for what constitutes 
the optimum size for a module. Van Tassel [8] states as a 
general rule that modules should contain bdDéetween 13 and 122 
high level language instructions. Meyers [5] gives es a 
commonly used limit 60 lines of code. The main point is that 
a module should be easy to keep in mind and comprehend. It 
Should ve noted, though, that ovorograms can increase in 
complexity as the number of modules increases. 

A goal in using modules is to reduce complexity, 
which improves maintainability. Complexity can arise from 
three sources: functional complexity, distributed complexity 
and connection complexity. Functional complexity ocrurs when 


a module is made to do too many things. Distributed 
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Complexity occurs when a common function kas not been 
mmooeriy identified and Separated, resulting in its being 
accomplished by many different modules. Connection 
complexity occurs when modules interact on common data in 
unexpected ways. 

Tausworthe {12] describes two important measures for 
modularity (originally defined by Meyers [45]): module 
coupling and module strength. An optimal desien for improved 
Maintainability minimizes the relationships between modules 
(minimal connections) and maximizes relationships arong 
components within each module (maximum strengtr). 

Table III-1 [46] shows the various categories of 
both module coupling and module strength and ranks these 


categories from the best situation to the worst. 
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Data: 


Stamp: 


Woncrol: 


External: 


Common: 


Content: 


Pumetional: 


Clustered: 


sequential: 


Communicational: 


Procedural: 


Temporal: 


anole lili. 


MODULE COUPLING 


all communicatiors between them is via 
argumerts thet are data elements 


their communication includes an argurent 
that references a data structure (some 
of whose fields are not needed) 


an argument from one knowingly 
ittewences the flow-ot-control of the 
OTtmner, ©€.2s, Plag 


they reference an externally declared 
data element 


they reference an externally declared 
(i1.2., common) data structure (some 
of whose fields are not needed) 


one referSsnces tne contents of the other 


MODULE STRENGTS 


Modmices Sem Onm a sameie =s peel ric 
fUnGE LON —SeeWEate aarecord to Output 
file 


module is a grouno of functions sharing 
qr@aravsthucture wuste lily tO Nide ats 
representation from the rest of the 
system..only one function is performed 
per invocation-— “symbol table with 
insert and look-up function 


module action comprises severel 

RUMe timomen te Capdos gt te iddte elong—— 
update and write a record 

module action consists of several 
logical functions operating on some 
data-- print and punch a file” 


module elements are grouped for. 
SWeOr Comic. nedsons-— 1000 body 


module functions are or rela ted 
in time-- initialization 


Module Cheracteristics [46] 
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Seeotcructured Coding 

Aman Che mecreristic) Of StLrUCtUred Drcgrarming 15 
Mme use of structured coding. Structured coding is 2 method 
Of writing programs which are more easily understood and 
Memntatned. [It is based on the fact that arbitrarily large 
and complex programs can be written using a small set of 
basic programming structures. 

Bohm and Jacopini [47] demonstrated that three basic 
control Structures were sufficient for expressing any 
flowchartable program logic (Figure 3-2): "sequence , 
selection (if then else ), and iteration (do while ). 
These three control structures are often expanded to include 
"do until” and “case” type constructs (Figure 3-3). 
feel D-1679, for exemple, limits control structures used in 


programming to these five dasic types. 
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[FTHENELSE 


SEQUENCE 


PROCESS A 





: SF 
SEQUENCE IF THEN ELSE 


DOWHILE 









“WHILE” 
PROCESS 


LO WHILE 


Figure 3-2. Basic Control Structures 
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DOUNTIL 






“UNTIL” 
PROCESS 


DO UNTIL 


CASE 







PROCESS A PROCESS 8 PROCESS N 


CASE 


Pieomre S-o. tdditione] Control Structures 
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Meyers [5] provides a list of seven basic elements of a 
Structured program which should be applied to nelp reduce 
program complexity, promote clarity of thought by the 
programmer, and enhance readability of the program: 


-The code is constructed from sequences of three basic 
erements . 


-Use of the GOTO statement is avoided wherever possible. 

~The code is written in an accentable style (e.g. use 
meaningful variable names, avoid statement labels, avoid 
language tricks) 

-The code is properly indented on the listing so that 
breaks in ex@€cution sequence can be easily followed 
(e.g. a DO Staterent can be easily matched with the 
statement ending the lcop) 


=There is only one point of entry and one point of exit 
iaetoae code for e€ach module. 


-The code is physically segmented on the listing to 
enhance readability. The executable statemerts for a 
module should fit on a single page of the listing. 

-The code represents a simple and straightforward 
solution to the probdlem. 

Often, a program is written with 4 clear structure but 
is eventually modified by unstructured constructs. Fven if a 
bit exaggerated, Van Tassel [2] offers a graphic 
{llustration showing how a program’s original logic can 
become completely obscured as the need for changes or 
corrections develovs (Figure 3-4). Clearly, the maintenance 
ere such ea program would be extremely difficult. 

Misses trdates the point that not only the initial 


source code shoula be structured but subsequent changes to 
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meemcode must also follow structured constructs. TRIDENT ccs 
software provides an example of a project that followed a 
structured development approach but eventually lost some of 
the benefits of structured programming by application of 


non-structured techniques (e.g., use of patches) [11]. 
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label 
label 


label 


label 
label 
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label 
label 
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label 


label 
label 


Uns tructured 


IF p GOTO label q 1 


IF w GOTO label m 

ie 2 une s 1on 

GOTO label &k 
Voeemunc t 2on 

GOTO label k 

IF q GOTO label t 
4rfurctior 

Berne t 1on 

Crrunec + 1on 

IF NOT r GOTO label 5 
Daeune ti On 

GOTO label r 

fees GOTO Laver f£ 
Prune t 2 on 

IF NOT v GOTO label & 
joeeunet 100 

Kru ne tion 

BND function 

y etumne tron 

GOTO label v 

IF t GOTO label a 
Patwnetior 

Botunetson 

GOTO label w 

Ae rurct ion 

iepeahlialio hy brolral 

G function 1 
IF NOT u GCTO label w 
h 2unetion 

GOTO label u 

Preyer t COTO Tebel yx 
enmnc t 1 On 

IF NOT v GOTO label xk | 
J) fanet ion 

GOTO label k 


Parure (S=4 . 


Strve tured 


IF p THEN 
Amine U1 On 
Ba func G1 on 
2S qt HEN 
ot Sea 
Gr fie t 105 
4 PpOWRILE u 
Heer une cacon 
4 ENDDC 
fine? ion 


© 1uneti on 
6 DOWEILE r 

DS. ere teen 
NO 
Las een 

Sb fly e Ligon 
his © 

Eecrume bl em 
ENDIF 
Cc WNIT 
< IF w Foaan 

Jeune 61-ONn 


WO WD GN 


2 Ss) 
2 ENDIF 
EEon 


2c $SIF w TEEN 
Veron o: 1 Of 


(oO A ESS 
Peano 

2 ENDIF 

FNDIF 


RK etunc clon 
PAD “Pune tion 


Examples of Unstructured and 


Structured Coding [8] 
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C. LANGUAGE CONSIDFRATIONS 

No Single develcpment decision affects the 
Maintainability of a program more than choosing what 
languege it will be written in. Some aspects that should 
influence thet choice are discussed in this section. 

1. High Level vs Assembly Level Language 

Hopkins [48], in discussing software auality, made 
it clear where he stood concerning the use of high level 
languages when he stated The higher level the language used 
in programming the better. 

Lang [48] provides a brief list pointing out the 
very grave disadvantages of assembly langueges: 

-Apart from the few who delight in such intricaciés, most 
people find assembly language programs hardér to write, 
read, understand, debug and maintain than high level 
language programs. 

elt provides the poorest conceptual framework for the 
programmer to express the computing operations he wents 
performed. 

-~It is completely machine dependent, thus requirizreg any 
magrane Language program to be completely rewritten when 
it is transferred to a different machine. 

Glass [49] talks about the enormous benefit of 
programming in high order languages both in terms of 
mrmeoanetivity and reliability. He points out that high level 
language code requires many fewer statements tnan asserdly 
language; thus, there are many fewer chances for errors. 


Also, the high level language programmer is screened from a 


whole class of potential error situatiors related to 
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hardware intricacy since the compiler accomplish=s the task 
of making hardware dependent choices. 

To illustrate some advantages in using a hign level 
language vs an assembly level language, a simple algorithm 
has been coded in both the high level language Pascal 
(Figure 3-5) and the Intel 8@8@ assembly language (Figure 
3-6). The program is designed to read an integer from a 
console ard Maintain a running totalj when eae "@ is 
Mmmesented then the prcegram is to print out the total. 
Although, most programs are more complex than these simple 
examples, they are helpful in making comparisons between the 
use of high level language and assembly language. Ne claim 


is made concerning the elegance of the solutions or for that 


matter the utility of their function. 





Preoeram ADD; 
Var Number, Total:Integer; 
Begin 

Total :=@; 


Repeat 
Read (Number); 
Total:=Total + Number; 
Until Number = @; 


he rcemttotal— -Frotal) 
aveu 


Figure 3-5. Integer Addition Program Written Irn Pascal 
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mOLTAL: 


NUMBER: 


Pha : 


START: 


HESS aD & 


- 


DB Q 
DE g 
ORG 190@E 
MVI C,69E 
MVI B,60E 
aver GAS 0 
5 Lae TOTAL 
INR ¢ 

CALL POSCUR 
CALL READ 
ANI OFE 
STA NUMBER 
LDA TOTAL 


foe nee DER 


ADD Mv 

DAA 

STA PTOTAL 
LDA NUMBER 
CPI 23H 

JZ DISPLY 
JMP START 
CA tePOSCUR 
MVS 
CALL PRINT 
NRC 

CALL POSCUR 
MVI A,‘°U’ 
CALL PRINT 
INR C 

CALL POSCUR 
MVI A,°M~ 
CALL PRINT 
INR C 

CALL POSCUR 
Me diay oe 
CALL PRINT 
INR C 

CALL POSCUR 
PDAM TO PAL 
RRC 

RRC 

RRC 

RRC 


POS Gun. 


READ: 


PRINT: 


END 


ANI FB 
ORI fe 
CALE PRin tT 
PVE C 

CALL POSCUR 
PDA LOT It 
ANI 2OFH 
GRI a2H 
CALE PRING 
Roo 2 

MVI A,@CBH 
Cpl REND 
MOV A,C 
Cai FR Ne 
MOV A,3 
CAUIn er Rel Nel 
RET 

PUSE 8 
PUSH D 
Puen a 
ee 
CALL O52 
POP # 

POL wp 

ee) os 

RET 

PUSH 8 
PUSH D 
ruse # 
PUSH PSW 
MV SG ee 
MOV E,A 
CALL @5H 
POF PS* 
POP 8 
Por. 

POP RB 

Bice 


Integer Addition Program Written In 
Intel 8980 Assembly Code 





Perhaps the most striking difference is in the 


program lengeth. For the high level language program only 12 
statements were used. This compares with &2 statements for 
the assembly language program. Another Sion roan 
difference is in readability. The high level language 
statements are more English-like (e.g., Begin, Fnd, Repeat, 
Until, Read, Write) and, hence, more comprehensible, while 
the assembly language instructions (¢.g., LXI, MVI, INK} are 
generally more abbreviated, reauiring increased 2ffort for 
understandine. 

Another noteble difference is that the details 
associated with the hardware interfaces are hidden from the 
hign level language programmer. Items such as merory 
location ‘aye the program, register usage allecation, 
conversion of ASCII code to binary coded decimal and back 
again, and cursor control for the terminal display are all 
Mmeemomtnat have to be considered and accounted for in the 
assembly language program. This increasei level of 
complexity provides Significant opportunities OF 
programming SrroncuUnusS Increasing tne difficulty of 
mMerntaining the program. 

Finally, consider the degree of difficulty that 
meomtd )6 Ox1St)60f or correcting an error in this simple prograr 
Or the amount of effort that would ve required to add 


enhancements (e.g., to obtain the average value). Clearly, 





the high level language program is more suited to this 
“maintenance type work. 
2. DoD’s Use of Figh Level Language 
a. Standard High Lev2l Languages 

DoD is taking action to reduce the proliferation 
of programming languages in an effort to improve the 
maintainability of future weapon system software ard _ to 
increase the transfer of available software among new 
systems [29]. 

Under Dol Instruction 5807.51, weapen system 
development programmers are restricted to the use of one of 
mamemrollowing high level languages: TACPOL, CMS-2, SPL-1, 
JOVIAL, FORTRAN, and COBOL. 

A continuirg effort is underway to standardize 
even further, to adopt one common high level language. A set 
of technical requirements for the common larnguege was 
developed, and during 1976 twenty-three existing lanzgueges 
were evaluated against these requirements. The findings were 
that no language completely satisfied the requirements, that 
several languages could be sufficiently modified to produce 
an acceptable language, and that it would be rossibdle to 
produce a language that would satisfy essentially all the 
requirements [5?@]. 

db. ADA 
DoD has subsequently adopted é commcn 


programming language based on the language PASCAL to use as 
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: ; 


its future high level language for emoedded computer 


software [51]. It has been named ADA, after Ada Augusta who 
became the first programmer as an assistant to Charles 
Babbage. 

Ota rue —iStmrace- it’. appears that one common 
programming language for DoD embedded tactical softwares 
would greatly improve Maintainability through 
Standardization and increased familiarity by a larger number 
of programmers. Alsc, a new language could be designed to 
incorporate the latest language methodologies for improved 
meoegram clarity. 

ADA is not, despite these apparent advanteges, 
universally accepted in its present form. LPijkstra (352], for 
example, has the opinion that it is neither complete, ror 
concise and expresses concern over its size by pointing out 
that ADA’s reserve word list amounts to ‘more than ten 
Mercent of basic Fnglish. ‘Also, he States raintainability 
is hampered dy the multiple ways that exist for doing the 
same thing. 

Regardless of this lack cf universal support, 
the ADA project is going forward and the Army plans to have 
a compiler ready during 1981. The Navy seems somewhat less 
aggressive in pursuing this common high level language 


eamort (51, 53]. 





c. Navy’s Use of CMS-2 

The Navy is reluctant to accept ADA partially 
because it has already standardized to CMS-2 which was 
designed Primarity for real-time, command and control 
applications. [It combines features of FORTRAN, COBOL and 
JOVIAL and has had continuous modifications, corrections and 
enhancements over several years of actual use. This is 
contrasted with ADA which is completely new and has had no 
previous use. 

Be ratchineg 

Before leaving the subject of programming languages, 
the use of patches must de addressed because of their 
detrimental effect upon software maintainability. 

A patch is a change made to the object program after 
it is assembled or compiled. Patching is generally 
acknowledged to be a bad programming practice yet it 
continues to occur. Its use is encouraged by rigid testing 
schedules since it provides expedient solutions [54]. 

Bovina bDSTAND 9S “and MIL-STDP-1679 lirit the tctal 
number of patch words to less than @.@@05 of the total 
machine instruction words in the program, but despite such 
attempts at limiting its use, patching can quickly get out 
of control. A small sample of the TRIDENT CCS software was 
hexen and found to have five times the current limits 


allowed Dy tiie newWounmhEL-Sip-1679. This is one reason 
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moeeene Haintainabdllity of this software has become a matter 
feaecOncern. 
BeeeeuLOMATED AIDS 

There is little disagreemert that, in order to produce 
maintainable software, the development must proceed in an 
orderly, flexible and measurable marner, with all phases 
clearly traceable from system requirements to machine 
Readable code. 

This entire process is extremely labor intensive and 
subject to errors of commission and omission. [t is not a 
novel idea to suppose such an effort could venefit from 
automation. Many automated tcecols have, in fact, teen 
designed and employed with varying degrees of success. 

It is beyond the scope of this thesis to include a 
comprehensive study of the strergtns and weaknesses of such 
tools, but a few methodologies are presented to serve as 
examples of this trend because of the significant influence 
it might have on the way software 1S maintained in the 
Puture. 

A problem statement language (PSL) and a problem 
Statement analyzer (PSA) are two tools developed at the 
University of Michigan to aid systems design. PSL and PSA 
are used by a number of large commerciel orgenizations. 
Chase Manhattan Bank is one example and it feels that ody 
using these methodologies, its software is now easier to 


maintain (55). 
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Tha, workire for the U.S. Army Ballistic Missile Defense 
Advanced Technology Center has developed a software 
requirements engineering methodology (SREM) which applies 
specifically to large, real-time weapon systems [46]. SREM 
memmmcoesiened to generate clear and complete requirements and 
momracilitate their modificetion. Since incorrect or missing 
requirements account for a large portion of errers in large 
software projects, the use of -SREM should improve 
maintainability. 

A highly ambitious software development and Maintenance 
Support system (SDMSS) is veing designed to automate the 
various activities for large scale software. It iS comprised 
of several subsystems, including requirements engineering, 
design, documentation, software error managemert, and 
maintenance. Reference [56] contains a rore complete 
Mmeseri option of this system. 

The source code control system (SCCS) is designed for 
controlling changes to files of text such as source code and 
software cdocumentation and aids maintenance Sriorts 
considerably. The current version has been operational at 
Bell Telephone Laboratories since 1977 [57]. 

A library control program (SYSM) has been developed by 
Magnavox and is currently being used to control a total of 
200,000 lines of code. It aidS maintenance by controlling 


changes in a secure and traceable manner [£8]. 
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Boy ohe OREM io UMoo, oGCo, and SYSM are only a limited 
set of automated tools being developed which will support 
maintenance activites. DoD must continuously stuay and 
evaluate these and similar methodologies for tossibdle 


applications to its weapon system software. 
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IV. DOCUMENTATION FOR MEETING MAINTENANCE REQUIREMENTS 


A. GENERAL 

The ‘Documentation Standards, Volume VII, of IBMs 
Structured Programming Series [59] states that 
“documentation in some form should de acquired for all 
software developed in order to support the future needs of 
software maintenance. It is obvious that a computer program 
eeoneaq ir Machine readable form on a media such as tape is 
not adeauate to meet the requirements of the maintenance 
programmer. The question becomes what type and now much 
moeunentation iS sufficient. This question must ve correctly 
answered if maintenance activities are going to be 
epuccessful. 

In determining what specific documentation should be 
produced and maintained concurrently with weapon system 
programs, some general guidelines should be kept in rind. 

har s by documentation must provide Owe complete 
traceability from the user’s operational recutrements to the 
actual lines of code so that if a requirement changes then 
ae app ROrrilave Code scan oe NCOrreet ly “modified, cr, 
conversely, if an error is found in a section of code the 
full impact on the user’s requirements can be determined. 

Second, the documentation must be easily modified. As 


requirements or programs are changed then correspcndine 
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emairees must be made to the documentation. If this is not 


done, then the documentation soon becomes outdated. This 
Mmeedesror concurrent Maintenance of documentation with the 
software makes those documentation forms that can be 
computer generated vrefeorred. 

Finally, because of the high cost of documentation, the 
amount produced should be kept to the absolute minimum 
required. Tausworthe [12] provides a graphic example showing 
the relationship between program costs and the level of 
documentation (Figure 4-1). Note that there is an optimum 


level that must be strived for. 


DEVELOPMENT 
(S/LINE OF CODE) 


MAINTENANCE 
(S/ALTERATION) | 


SOFTWARE COSTS ($) 





| 
| 
| 
? 


? 
PROGRAM DOCUMENTATION LEVEL (PAGES/LINE OF CODE) 


Figure 4-1. Program Costs vs Documentation Level [12] 
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In this chapter some examoles of formal standards are 
identified which have been developed within DoD concerning 
the production of decumentation for use in the maintenance 
Of software. Also, available forms of documentation are 
discussed which are specifically used for representing 
program design, arn important need of the maintenance 


programmer. 


B. MAINTENANCE DOCUMENTATION STANDARDS 

A limited set of stendards have been develonved at 
yarious levels within ToD which specify the content and 
format of documentation to be used to suvport software 
maintenance activities. mxamples of these are provided in 
ocaerT Gomme Gemorstrate tae Nature and extent of these 


standards. 


1. Program Maintenance Manual 

DOD STANDARD 7935.1-S, ‘Automated Tata Systems 
Documentation Standards, 13 September 1977, provides 
guidelines for the development of a Program Maintenances 
Manual. The purpose of this manual is to provide the 
maintenance programmer with the information necessary to 
effectively maintain a system. A copy of the format of the 
Program Maintenance Manual is given in Appendix A. Note that 


it is oriented towards documenting data base systems rather 


than weapon systems. 





Peeecim@oct osvStemessoerem Lescrintion Documerts 


en 
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PocNaviNS) Wesoga! iS one of the Fost corplete sets 
of documentation standards specifically for weapon system 
Software. Vithin this Navy Standard three docurents are 


CLicel 


ap 


Meempitiec which support the méeintenance of t 
software. Categorized under the general heading Combat 
Pepe Program [escription Group, thev are called: tne 
Program Tescrinvtion Document (PDD), Data Base Tesien (DED), 
and Frogram Package (P>). A description of their purpose érd 


feo Of their formet is provided in Anverndix 3. 


eee bee NATIVES FOR REFRESENTING PROGHZAM STEUCTULE 

As the previous section illustrates, there has beer some 
SeeaodradiZation for maintenance documentation te foliow. The 
remainder of this chapter 1s deveted to a discussion of 
those tools available for representing a program’s internal 
eeemmeture. This is an @rea that hes not been standardized. 
In fact, there is considerable diSagreerent as to what tools 


epeethne test to use. 


ime flowcharts 
NaemmovOwecert 45 42 -Sraphic representetion of a4 
program logic. Its purpose is to make it easy to see the 
Memat2Onsrips ang flow of control among the various design 
Glements. It is a technique that has been so widely vsed 
Since it was developed by von Neuman in 1947 thet a set of 


mapbomdl standards exists for flowchartinge symbols [4£¢]. 
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Many individuals, however, are opposed to the use of 
flowcharts. Prooks [61] calls the technique an obsolete 
nuisance, and a most thoroughly oversold piece of program 
documentation. Aron [€2] feels that flowcharts are useless 
to a programmer when diagnosing errors. Weinberg [63] states 
“we find no evidence that the original coding plus flow 
diagrams is any easié€r to understand than the original 
codirg itself--except to the original programmer. These 
comments bring into question the value flowcharts have for 
the maintenance programmer. 

Schneiderman, et.al. [64] decribe a series of 
controlled experiments which test the utility of flowcharts 
as an aid to the full range of vrogramming activities: 
composition, debugging and modification. Although their 
Original intent was to determine when flowcharts were most 
tememul, the experimentel results led them to conclude that 
flowcharts are a redundant voresentation of the information 
contained in the programming language statements. Their 
conjecture is that flowcharts may even be a hindrance 
because they are not as complete (omitting declarations, 
Statement lables and input/output formats). 

To provide an example for illustrating some voints 
to consider when using flowcharts as amairtenerce tool, a 
series of four pages of flowcharts which represent the logic 
in a TRIDENT CCS module will be used (Figures 4-2 through 


4-5). For simplification, the labels used in the flowcharts 
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have been changed using the convention: (Ti) for terminals, 
Mieeeror decision points, (Ci) for connectors, and (Pi) for 
processes. 

These flowcharts were chosen as examples because 
they represent a small, logically clear section of cede. 
mecoradinge to tke flowcharts, this section of code can be 
entered only through Tl, Figure 4-2, and exited only through 
freee yocure 4-4. A stopping condition exists at T35, Figure 
aS). 

PicmeiarStmmpOLrt to be Jllustrated concerns the use 
Geemconnectors. The connectors used in the original TRIDENT 
flowcharts are statement labels and could be used as entry 
points from other portions of the program. The use of single 
connectors embedded in a sequence of code such as Cl, Figure 
4-2, is unnecessary since no additional entry cvoints are 
designated. By checking the actual code, through the use of 
the cross-reference listings, it was détermined that this 
label was, however, used by a subsequent branch point. A 
modified version of the flowchart in Figure 4-2, which more 
accurately represents the programs logic, is provided in 
Figure 4-€. The point is that all possible entries to a 
program should be clearly designated. If no entry poirt 
exists then labels are not needed and should be eliminated. 
Motto ao SO.creates the possiblity for potential errors. 

MSP Cands POlRt tomconsider is the ability to trece 


Preroveaea SECtton of logic. Golng from beginring to end is 
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Metatbively easy, but consider tracing through the reverse 
ferection. Often, the malntenance vrogrammer is left with a 
specific program state, and his job is to determine what 
conditions created it. For example, using Figures 4-2 
through 4-5, if the maintenance programmer needed to 
determine what sequence cf contrel could have led to the 
stopping condition (T2), Figure 4-5, it would be recessary 
Momtrace backwards through all four pages of flowcharts. 
This problem is compounded when dealing with numerous pages 
Or tlowcharts and multiple branch points. 

Yeaniecie DOlnt  tOemcOnsamer® is. the difficulty of 
Maeine changes to the docurentation. Note that substituting 
a decision block (D2A) for a procedure block (P2) in Figure 
4—2, in order to more accurately represent the programs 
logic, required that a completely new flowchart be 
constructed, “igure 4-6. 

It should te noted that the Software Acauisition 
Maragement Guidebook, Software Maintenance Volume [27], 
recommends that Def not procure flowcharts with delivered 
software, and MIL-STD-1679 states that ‘there is no 
requirement that flowcharts be a deliverable item. 

In Conerace CL OnN TO. tnlsS Seuscances SECNAVINST 
5560.1, when describing the Program Description Tocument, 
States (a flowchart shall be included for each major 
Mreecedur] Or subroutine that depicts detailed operations 


performed by the subdprogram. 


bY 





ao) line = 
8 OPO E 
=< 


Figure 4-2. Example Flowchart, part 1 of 4 
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Figure 4-3. Example Flowchart, part 2 of 4 
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Figure 4-4. Example Flowchart, part $3 of 4 
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Pigure 4-5. Example Flowchart, part 4 of 4 
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Flgure 4-€. Modified Flowchart 


ie 


eematerarchy Pius Input—-Pprocess—Output (HIPO) 

FIPO was develoved as a design aid and docurentation 
technique by IBM and is described in [65]. It attempts to 
pmeviae more than just representing the program logic as 
flowcharts do. It empvhasizes the functional aspect of the 
mreofram and its data flow. Malntenance efforts are said to 
be facilitated by making it easier to trace a function that 
needs to be modified from the docurertation to the actual 
code. 

A HIPO package consists of three kinds of diagrams: 
a visual table of contents, overview diagrams and detail 
diagrams. Thes2 diagrams provide a graphical description cf 
the program’s function from the general to a detailed level. 

Figure 4-7 shows the structure of a typical HIPO 
package. Note that the visual table of contents shows the 
Structure of the diagram package and relationships of the 
mometyons in a hierarchical fashion. The overview and detail 
HIPO diegrams contain the inputs, processes, outputs and 
extended descriptions at each stage of the successive 
eeecormposition of a progran. 

nea, does not enjoy universal support as 24 
Maintenance tool. In a survey by Anderson and Shumate [66], 
Semauctec to find out What docurentation tools were found 
useful by maintenance programmers, HIPO was ranked as the 
least preferred form when compared to the prograr listings, 


English language narratives, flowcharts, hierarchy diagrams 





and the data base design documerts. The authors felt that 
EIPO documentation is an important design tool but seers to 
have a lesser value for maintenance activities. 

Meyers [5] contends that while HIPO diagrams are 
superior to the flowchart because they show e¢data flow as 
well as control flow, HIPO diagrams are not needed for the 
Same reasons that flowcharts are not needed for maintenance 
type Monee caSicaliy, he teels Doth merely duplicate 
meeormation that is already contained in the trogram 


mrestines. 





t A Vewat Table of Contents 


Figure 4-7. HIPO Documentation [€5] 
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&. Decision Tables 

Decision tables provide a faunlar form of 
representing program design and have been used as a 
Maintenance tool. Generally, decision tables ére made up of 
a set of conditions, each of which may be evaluated as true 
or false at any given time. The truth or falsity of these 
conditions ray be combined in various ways, alorg with a 
series of actions, to form what is called a decision rule 
(i.e., a set of conditions that must be satisfied in order 


that a series of actions be taken). 


COND TE Lehe sd Us CONDITION ENTRY 





ACTION STUB ACTION ENTRY 


Table IV-1. BDecision Table Structure 


Aceevuiustratved ~in Table IV=1, it is divided into 
four quadrants. The upper left quadrant, Cai ed the 
Sondition stub, contains all the conditions being considered 
mone a Derticular decision rule. The condition entry, in the 
upper right quadrant, combines with the condition stub. to 
mean tne condtion that is to be tested. Toe action stub, in 
the lower left quacrant, contains actions resulting from the 


conditions tested above. Action entries, in the lower right 


fe. 


quadrant, serve to indicate responses to the indicated 
combination of conditions. 

ieee condition wa the condition stib is true, a  Y 
memmmenverea for that particular rule in the conditior ertry; 
if the condition is false, an N would be entered. Ir a 
Seuuadtion where a particular condition is irrelevart a 
don’t-care would be indicated by use of a dash, “-.. An ‘X. 
specifies actions to be executed. An example of a decision 
table for representing a Ssirvle process of 


approving/disapproving loan reauests is presented in Table 


ee 


LOAN TABLE Rl R2 RS R4 


Satisfactory 
Credit limit 


Favorable 
Payment History 


Special Clearance 
Cotained 


Approve Loan 


Reject Loan 





Table IV-2. Example Decision Table [6&7] 


Cne advantage of using decision tables is that it is 
possible to convert them into compilable source code via a 
preprocessor (67, 68]. The additional computer time required 
nor compilation can be offset by reduced effort for 


programming both during the initial ovrogramming phase anda 


me 





the maintenance phase. Another big advantage of decision 
mepes 15 that their concept and structure causes the number 
of overlooked situations and program inconsistencies to be 
reduced. 

The B. F. Goodrich Chemical Company is one proporert 
on the use of decision tables. Reference [16] revorts that 
Goodrich has used them extensively and finds that complex 
Mozic becomes clearer and there is less chance of 
overlooking a logical path. Goodrich estimates that overall 
productivity for analysts and programmers in maintaining its 
COBOL~bvased systems has been at least double what it would 
have been without decision tables. 

Another successful example concerning the use of 
decision tables is reported by Fisher [69]. An extremely 
Complex file maintenance problem arose at the USAF Automatic 
Resupply Logistic System at Norton A¥3. Almost sever 
mean=years had been spént trying te define the problem using 
memrative descriptions and flowcherts, but to little avail. 
A crash program using decision tables was then implemented. 
Four analysts spent ore week establishing the decision table 
format. Three weeks later the problem was solved. 

To help determine whether the use of decision tables 
is appropriate for documenting programs such as the TRIDENT 
CCS, a section of logic was translated into a decisior table 
format Table IV-3). The logic represented is the same as 


that shown in Figures 4-2 through 4-5. Note that identical 
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imoerc Contained in four pages of flowcharts has Deen reduced 
to a clear, concise table taxing less that one nage. This 
points out, also, that revision of decision tables reauires 
less work than modifying flowcharts. This is an important 
consideration for maintenance activities where revisions are 


expected. 


Jed 


bie bo 


P4, PS 


jiorhe ©) 
RETURN 
Paget 2 
STOP 





Table IV-3. Example Program Logic 


Two disadvantages of decision tables are: (1) 
possible ambiguities may arise when don’t care ccnditions 
are presented and (2) decision tables are of little help 
when the ovrogram logic involved is not decision-making 


oriented. 
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While decision tables may not always be anpplicable, 
the previous discussion illustrates that they serve as an 
alternative form of documentation that should be considered. 
Federal Information Processing Standards Publication 38, 
"Guidelines for Documentation of Computer Programs and 
Automated Data Systems, 15 February i976, states that 
omemer flowcharts or decision tables, whichever is more 
approvriate, can be included or appended to docurentation 
for software. Yowever, SHCNAVINST ZSE¢G.1 makes no mention of 


their use. 


4. Nassi-Shneiderman Charts 

Witmer ne aaqvent Of Structured DrogrammMirge technolorsy 
a form of structured flowcharts has emerged. Developed by I. 
Nassi and B. Shneiderman in 1972, they can serve as a 
praphic representation of a modules logic desien and provide 
a maintenance pregrammer with a quick reference for finding 
the code performing any logical function. The advantages 

Claimed for these charts include: 
—-The scope of IF THEN ELSE clauses 1s well-defired and 
visible; moreover, the conditions or process boxes 
embedded within comvound conditions can be seen easily 


from the diagram. 


-The scone of local and globval variables is immediately 
ovvious. 


SAPO trary transfers of control are impossibie. 


—-Complete thought structures can and should fit on one 
page (i.e., no off—page connectors). 
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Yoder [(76} provides a thorough description of the 
meromect eN—o Charts. Priefly, tne charts are constructed by 
combining and nesting the basic structures shown in Figure 
4-8. An example showing an extension of the use of the basic 
SyergolLs, which illustrates a N-S chart to calculate and 
Mrint an FICA report, is shown by Figure 4-9. 

N=-S chants are strongly linked to structured 
Mmacenamming constructs, thus, it may be difficult to anply 
Mmeecee form of documentation to rnon-structured portions of 
peoeram logic. 

The method of N-S charts has not been PULL y 
exploited in actual practice and little information exists 
in the technical literature advocating their use. They are, 
nevertneless, an alternative form of documentation that may 
be considered for use as a maintenance tool. 

The section of logic previously represented by 
Figures e-e2evrrougn 4-5 ‘and vby Table IV-S hes been 
represented using N-S charts (Figure 4-19). This illustrates 
meee potential of using N-S charts as a maintenance tool for 


pemecware such as the TRIDENT CCS. 
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ELSE THEN 
CLAUSE CLAUSE 


Process symbol Decision Symbol 





FHOGESS 


STATEMENT 





DO WHILE CONDITION 


UNTIL 
PROCESS 


WHILE 
PROCESS 


DO UNTIL CONDITION 





DO WRILE Symbol DO UNTIL Symbol 


[=] iz=2 t=n 


PROCESS PROCESS PROCESS 





CASE Symbol 
Figure 4-8. Five Basic Structures of N-S Charts [72] 
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READ THE FIRST PAYROLL RECORD 







DO WHILE THERE IS MORE DATA TO PROCESS 






YEAR - TO- DATE FICA LESS THAN 
MAXIMUM ? 






CALCULATE FICA 
DEDUCTION 







YEAR - TO- DATE FICA PLUS 
DEDUCTION > 











SET FICA 
DEDUCTION 
TO ZERO 










SET DEDUCTION 

SO YEAR - TO - DATE 
WILL NOT EXCEED 
MAXIMUM 












ADD DEDUCTION TO 
YEAR - TO- DATE FICA 


SET NET PAY TO GROSS PAY MINUS FICA DEDUCTION 

PRINT NAME, GROSS PAY, FICA DEDUCTION, YEAR - TO - DATE 

FICA, NET PAY . 
READ NEXT PAYROLL RECORD | 





Figure 4-9. Example N-S Chart [79] 
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Figure 4-10. Nassi-Shneiderman Chart For TRIDENT 
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Se er rorram Listings 
It would be highly desirable if programs could be 
made self-documenting, thereby, eliminating the necessity of 
maintaining rultiple forms of docurentation revresenting the 
same logic. Many authors advocate such an approach through 
Serueturing program listings. Meyers {5], for example, 


states: 


Since we already have the code, why not let it serve as 
mae. Lloeic documentation? . . . additional documentation 
such as a flowchart would tbe undesirables because it 
would be redundért with the code. Redundancy in any type 
of documentation should de avoided because it increases 
Maerctrances of conflicts. Furthermore, unless care is 
taken to update the documertation (which is more 
Orericult if the logic documentation is ohysically 
sevarated from the code), redundant documentation often 
vecomes totally useless after the code is modified a few 
times. 


In his 1974 ACM Turing Award Lecture, <Xnuth (71) 
addressed the importance of program listings when he stated: 
There are many senses in which a program can be “good. 
of course. In the first place, it s especially good to 
Mave a prograr that works correctly. Secondly it is 
often good to have a program that won’t be hard to 
change, when the time for adaptation arises. Both of 
these goals are achieved when the pregrarm is easily 
readable and understandable to a person who knows the 
appropriate language. 

Anderson’s study [66], discussed previously, has 
illustrated the importance of prcgram listings as compared 
to other forms of documentation for maintenance work. Again, 
this study found listings were the maintenance programmer’s 


"most useful tool. 








What constitutes a self-documertizneg program? 
Bren eavINST 3560.1 states that the listing will be an exact 
duplicate of the delivered card decks cr magnetic tape. It 
mmepnper States that each compiler source staterent will be 
annotated with comments, or, if the source is assembly 
level, then a comment shall be 1listed for each assembdly 
level line or function group of lines with not less than an 
average of on® comment per five statements. No mention is 
made of the tyne or form of commerts. 

eto meoco provides much more explicit direction. 
Mreetates, in part, that: 


A narrative description shall describe the 
history and identify the functions of each hierarchical 
component of the weadon syster software. 


Each component shall include at the beginning of 
the executable coding a textual description of its 
mmoutsS.  OUtputS, function or task, and algorithms; a 
list of other components called; and a list of all 
calling components. In addition to general explanations, 
to assist understanding, precise references to the 
appropriate statement labels and datea-names shall be 
included se each module, procedure and routine 
descriptive abstract. The descriptive abstract shall 
define the allowed and tolerable range of values for all 
inputs and shall define the allowed and erpected range 
of values for all outouts. A history of the original and 
updating programmer names, the activity or commercial 
company name and the activity or company division code 
or billet identifier with dates completed shall be 
included. iy 


ine order to facilitate orogram comprehensior, 
comment statements shall be used throughout the program 
code. Comment statements are non-executable (i.e., they 
have no effect on program executions) and are used to 
provide documentation and clarification of the logic, 
data, variables, and algorithms. Eacn source statement 
shall be self-defined or defined by a commert phrase to 
a level understandable dy a verson not associated with 
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the original e¢developmert effort. Logical grouns of 
comment phrases may be included in a single comment 
statement. General comments on grouvs of source 
statements performing logical Legcaen OS shall be 
included on separate comment statements. 
The Tactical System Programming Support Pranch of 
Opes Marine Corps Tactical Syovem Sup Oe t Metiy ita, 
responsible for maintaining the Marine Corps” tactical 
software, considers the computer program listing to be the 
single most important tool for software maintenance. It has 
developed a set of standards to ensure listings are properly 
designed and coded. This standard serves as a possible 
example for other maintenance organizations to follow. See 
Appendix C. 
Botne MiL=SiTD=1S69 and SECNAVINST S56¢@.1 address the 
use of cross-reference listings which are included here as a 
portion of self-documentation since they Can be 
automatically generated from the program listings. Tney are 
considered a necessary maintenance tool since they identify 
every place an item (e.g., variables or subroutines) appears 
in the program, so when tne item is changed or modified the 


impact on the remaining portions of the pregram can be 


guickly determined. 


6. Summary 
This section has illustrated a variety of techniques 
used for representing program design to the maintenance 


programmer. Clearly, no one form completely represerts all 


a7 





aspects of program desigr. AS programming methodologies 
become more structured, the trend towards increased erphesis 
Payne use of program listings should continue, reducing the 
need for supplemental ferms of program documentation. 
Although, it seems unlikely the need for some tyne of 
eraphic representation will ve totally eliminated. There is 
an important psychological aspect of conveying meaning 
through pictures that cannot oe duplicated with narratives. 
No doubt, a variety of documentation tools will always be 


necessary. 
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Ve. SOFTWARE MAINTENANCE POLICIES WITSIN COD 


A. BACKGROUND 

This chapter provides an overview of policies and 
methodologies existing in DoD which affect weapon system 
software maintenance. First, the publications that contain 
applicable policy guidance are reviewed. Next, tne results 
from a limited survey of agencies involved with weapon 
system software maintenance are presented. Finally, there 15 
a discussion of pertinent research and develoovrent work. 

It is imvoortant to realize that the policies and 
methodologies for procuring weapon system software have been 
feererent than that used for ovrocuring automatic data 
processing equipment (ADPE). The distinction med2@ vdbetween 
these twe categories of autemated systems is a result of the 
1965 “Brooks Act (Public Law 89-306, 4@, U.S.C. 759). 

The Office of Management and Budget {OMR) and the 
General Services Administration (GSA) administer the Brooks 
Act guidelines. ADPE is controlled by this act and falls 
under the purview of the Assistant Secretary of Defense 
(Controller). Weapon system software, however, is excluded 
meome the provisions of this Act and fall under the 
MmirmrsarOotioue Or tae Office of the Undersecretary cof [Lefense 


for Research and Engineering. 
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PeeCU2RENT POLICIES 

There has been ro centralized source of guidance with 
respect to weapon system software maintenance for DoD 
organizations to follow. Many directives, regulations, 
specifications, and standards have, however, influenced 
weapon system software maintenance to varying degrees. The 
Gemegmeotenificant of these are listed in this section. Even 
though most of these have been introduced ir previous 


chapters, they are consolidated here for ease of reference. 


1. MIL-STD-4E3 (USAF) 

MIL-STD-483 (USAF) “Configuration Management 
Practices for Systems, Equipment, Munitions, and Computer 
Programs, 1 June 1971, defines the entire spectrum of 
activities associated with controlling changes (a critical 


need for maintenance work) to computer programs. 


Pome 


2. MIL-$—-52779 (AD) 

MIL-S-52779(AD), “Software Ovality Assurance Program 
Requirererts, 5 April 1974, requires that a Quality 
Assurance Program (QAP) be implemented spscifically for the 
developrent of computer programs and related documentation. 
Even though this standard is concerned with the development 
phase, it is important to software maintenance because it 


directly effects the auality of the software. 
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camo CNAVINST 3569.1 
SECNAVINST 3568.1, Department of the Navy Tactical 
Digital Systems Documentation Standards, 8 August 1974, 
identifies, names, and describes that set of documents 
necessary to support both the development and maintenance of 


tactical software. 


4. DODDIR S828 .29 
TODDIR 5@08.29, ‘Management of Computer Resources in 
Major Defense Systems, 26 April 1976, establishes DoDP 
policy for the management and control of computer resources 
during system acquisition. Maintainabdility of software is 
called out as a major consideration during initial design. 
ieeeatso directs that support items required for cost 


effective maintenance be specfied as deliverable items. 


Peel oeSTD-1521 (USAF) 

MIL-STD-1521 (USAF), Technical Reviews and Audits 
for System, Equipment, and Computer Programs, 1 June 1976, 
Meescrioes the requirements for the conduct of technical 
reviews and audits in conjunction with the documents defined 
foeeett i —-S i D-48S3. Direction is provided concerning the review 
and audit of computer program configuration items ard their 
associated documentation. Each type of review or audit is 
described in an appendix to the standard and can serve as a 
basis for checking Comollvarce eae maintainability 


requirerents. 


91 





6. DODINST 5808.31 
LODINST 500@.31, Interim List of DoD Approved High 


Order Programming Languages (HOL), 24 Noverber 1976, 
Specifies the HOLs which are approved for use in conjunction 
with DODDIR 5000.29. Although this instruction allows for 
Semtain @€xceptions, it attempts to reduce proliferation and 
ensure control of HOLs in defense systems by limiting new 
fevelopment to six approved languages: CMS-2, SPL-1i, TACPOL, 
JOVIAL, CCEOL, and FORTRAN. 


7. MIL-STD-1679 (NAVY) 

Wil ot D679 (NAVY), “Weapon system Software 
Development, 1 December 1978, establishes uniform 
requiremerts for the development of weapon system software 
mepein DOD. Strict adherence to the provisions of this 
Standard will help ensure that the tactical software so 
develoved will be imoroved over current versicns of tactical 


software. 


C. SURVEY OF DOD MAINTENANCE ORGANIZATIONS 

moeintormal survey was taken of personnel from five 
different DoD organizations involved with the maintenance of 
weapon system software. While not voroviding cfficial policy, 
the results can be used to derive a general understanding of 
the environment in which they have operated, such as what 
problems have been experienced and what methodologies were 


used in performing maintenance activities. 
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1. Pacific Missile Test Center 

The Weapons Control and Software Systems Division of 
Meemerecitic Missile Test Center is involved with Fleet 
Support of tactical software for selected weapon systems 
Such as the F-14. 

The software, developed largely under contract, was 
being maintained vy in-house resources. Maintenance 
functions performed included configuration accourtirg, 
problem validation, training, analysis, design, change 
faenentation, documentation, verification and tape 
generation. The greatest amount On work has been 
necessiteted by software enhancemerts which required varying 
degrees of redesign. New tape versions were released 
approximately every 18 months. 

Competing Wi Uo eePi vate umanoustzy for) recruiting 
professional personnel has been a significant aa leis 
Another problem has been inadecuéete Software documentation 
Prom contractors. Concern was expressed that documentation 
has historically been one of the first items to be cut from 
software development budgets, a decision that has seriously 
degraded the subsequent maintainability of software. 

A jlarge effort has been rade to correct the problem 
of inadequate documentation. Guidance was beire formulated 
which goes beyond the requirements defined in SECNAVINST 
Soc adem iesile=iC/9 by improving the traceability from 


one level of system description to another. 
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The importance of using actual operational equipmert 
for program debugging and verification after maintenance 
changes were made was stressed. 

Memento Kee pe mel od@lozies peurrent 1Ssevlcent, 
but this effort is being strained by increased work loads 


and versonnel shortages. 


2. Naval Ocean Systems Center 

The Software Quality Control Organizetion at Naval 
Ocean Svewers — Center 1s hot directly responsidie for 
Maintaining tactical software. It did, however, perform a 
eritical Pune 1 on that greatly improves software 
fermmtainability. Activities include document inspection, 
configuration Management and test and evaluation during all 
phases of the acquisition cycle in order to assist procuring 
Organizations in acquiring higher Gvari ty and more 
maintainable software. 

One of the biggest problems encountered has been 
convincing managers that software requires the sare degree 


Of engineering centrels as hardware. 


S. Naval Surface Weapons Center 
The Fleet Fallistic Missil2 Geobellistics Division 
of Naval Surface Weapons Center is responsible for both 
wvetopment » ana Maintenance of Fleet ballistic missile type 
software such as the TRIDENT-I Tire Control System. Most of 


iets WOrk 1s aecomolished in-house with very little 
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contracting. There is no separate organizational group 
dedicated solely to the maintenance of software. Maintenance 
activities are integrated with developmert activities. 

As expectec, when software products were initially 
released to the flest the vast majority of maintenance was 
mecomplished in order to correct errors, but the ratio of 
improvements to error ccrrections increased as the time from 
initial release increased. One software product whica had 
been released for two years was experiencing maintenance c? 
approximately 50 percent for improvements and &¢ percent for 
peenon corrections. 

Changes to software are made according t70 a 
formalized configuration control plan. Releases of new 
versions have been made on the average of once per year. 
Pecenes were discouraged but used under restricted and 
metry controlled circumstances such as to correct critical 
errors between major program releases. 

Actual field eauipnment is used to test vrcegram 
ememees with the capability of using some real inputs. Most 
inputs, however, are simulated. 

pendradwaGewmont tor 15 used and found very useful for 
analyzing the performance of software. Another useful tool 
uséd is the ability to take core dumps which are analyzed 
via computer whenever vrcegram crashes occurred. 

A specially designed HOL called Trident High Level 


Language (TFLL), said to be even more structured than CMS-2, 
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was being used. Program listings are maintained in a 
Structured form, and a program design language (PDL), a 
pseudo high level language, is used to help document 
programs. 

The actual process of making changes to software has 
posed no significant prodlems, but understanding and 
verifying reported software errors from the Fleet did, at 


memes, present difficulties. 


4. Naval Air Develonment Center 

The Software ard Computer Pirectorate of the Naval 
Air Development Center functions as the software support 
agency for selécted avionics software such as that in the 
foo Orion. 

The maintenance of the FP-3C software is comvlicated 
by the fact that it is being converted from a tare 
configuration system to a drum configuration system. While 
the functional requirements remained the same, the details 
of implementation differed. Foth configurations must be 
Simultaneously maintained. 

The importance of defining to a fine detail 
maintenance requirements early in the developrent of 
software was Stressed. The cencepts of structured 
programming was advocated, but trying to implemert the 


eonstructs of MIL-STIP-1679 on existing software that 
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was originally unstructured presented many difficulties and 
was not recomrended. 

New program versions were being released on the 
average of every 18 to 24 months and patches were being 
used. It was stated that patches will always be reauired to 
some extent because of constraints such as delivery 
schedules. 

While the program listing was the cheapest form of 
peeoeram documentation, detailed flowcharts were considered 
useful as a maintenance tool. It was suggested that the 
autorated process of producing and updating flowcharts would 
Demnelpfrul. 

One of the biggest problems being experienced was 
item iarese personnel turnover rate that exists in the 
services. Maintenance of software would be an easier task if 


there were greater stability of personnel. 


5. TACFIRE Software Support Croup 

The TACFIR= Software Support Group is responsible 
for maintaining the software for the Army’s automated 
Artillery Tactical Fire Direction System (TACFIR=E), a system 
whose software was developed under contract. Maintenance of 
MmemsoftWware is still using contrector support. 

The group uses configuration control procedures much 
Tike the other organizations cortacted with a configuration 


control board setting priorities for approved software 
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changes. Approximately 75 percent of the changes experienced 
were the result of program e@nhancements and 25 percent 
Mmecessitated by program €rrors. New ovorogram versions were 
being released about every 12 months. Patches were 
discouraged but practically every release had ccntainei a 
iemated number. 

Both a ovrograrmming support system (PIP 11/25) and 
actual TACFIRE hardware were used for program cebugging and 
testing procedures. 

ieemecoGe for the software is written in the FOL 
TACPOL. Some code in the programs is assembly level. fae 
ratio of FOL lines of code to assembly level lines of code 
averaged roughly nine to one. 

The support group is deginning to cc software 
development work for a multiple rocket system. The software 
for this system is being designed to fit an existing set of 
hardware. The language used for this new software is 
assembly level, called Symoolic Interpreter Routine (SIR). 
The use of an assembly level languaze is necessitated by 
both hardware contraints and a desire to share ovoreviously 
written software modules. 

The only general ovroblem méntioned in mairteinineg 
weapon system software concerned the ai et iculyy of 
interpreting software trouble revorts submitted by using 


mnits in the field. 
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Eemrecine COrpssiectical System Support JActivity 

The Marine Corps tactical software is developed 
largely bvy contractors. Software maintenance of fielded 
systems, however, is centralized ard accomplished in-house 
by the Tactical Systems Prograrming Support Branch of the 
merine Corps Tactical System Support Activity. 

ime SOGtaware is Written in’ CMS-2 and kept highly 
Structured using the conventions outlined in Apvendix C. 
Listings provided documentation for the program’s logic 
Climinating the need for detailed flowcharts. The software 
is refined to the point that no major operational errors are 
@oserved. The Majority of maintérance was being necessiteted 
by program enhancements not error corrections. 

Software configuration management is Stricunry 
applied to all changes. New tape versions have been released 
adpout every 9 months. Patches had not been used in over two 
years and are considered contrary to good mairtenance 
practices. 

Two HOOrS. foUne Useful lo support maintenance 
Migurvities are the CMS—2 librarian to control coding changes 
and a hardware monitor to measure system performance. 

Actual field systems are available for oprogrer 
testing and debugging with the capability of usine both 


actual and simulated real-time inputs. 
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Bersonmel Were in favor of adopting the percegrammire 


language ADA and have been involved with the Departrent of 
Defense Hien Order Language Commonality Program since 1977. 
Problems mentioned included attracting and retaining 
qualified versonnel and educating top level managers about 
the nature of software. The technical aSpects of mairtaining 


software presented nce significant problem. 


D. RESEARCH TO IMPROVES SOFTWARE MAINTENANCE 

Wegner [72] states: 

software mainterarnce has only recently been recognized 

as a key area for software research. Research needs 

include the development of tools to allow understanding 

(readability) of software, modifiability of softwere and 

revalidation of modified software. 

Not listed in the previous statement is the reed for 
validating Claims that new software engine*ring 
methodologies significantly imvrove the maintainability of 
large, complex, real-time weapon system software. Since 
claims have not been demonstrated, there has been reluctance 
Prom some system developers to ‘Incorporate their use on 
eerual system projects. 

An ambitious, exploratory research project hés beeén 
initiated by the Naval Research Laboratory and the Naval 
Weapons Center in order to correct this situation. The 
project involves completely redesigning and implerenting the 


Operationad! flight program (OFP) for the A-7 aircraft usireg 


many of the new software engineering principles. The 
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redesigned program will be functionally identical to the 
existing A-v’ OFP so a direct comparision between the two car 
be made in areas such as software maintainability. 
Mmresuccessful, the final product could serve as a useful 
engineering model for subsequent weanon syster software 
meveltopments. For further information the reader is referred 


to the program summary, Appendix -. 
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VI. CONCLUSIONS AND RECOMMENDATIONS 


DoD Organizations are becoming more aware of the 
Significance that maintenance plays in the overall 1i?8 
cycle of weapon system software. Even as this softwares 
pecores more error-free, the relative Lm@porrvance of 
maintenance activities will continue because of frequent 
enhancements made to existing systems and increasing 
complexity of applications. 

To ensure that future weapon system software can be 
easily and accurately modified to correct errors or 
accommodate changes in user requirements, maintainadility 
must be considered es a2 primary design objective. 

The organization which will eventually be responsibdle 
for Maintaining the software of a weapon system must be 
allowed to participate in the development process, including 
the formulation of specifications and subsequent technica 
design reviews. 

The importance of programming standardization must be 
stressed because of the lone life of weapon system software 
and the relatively high rate of personnel turrn-over within 
DoD software maintenance organizations. Although software 
Standards have not yet reached the refinement or level of 
meron thateexast for hardware, MIL-STD-1E€79S represents a 


Sood overvine point. If complied With, this standard should 


182 





Significantly improve the maintainability cf weapon system 
software. 

How much and what kind of documentation will be 
delivered with weapon system software are among tne most 
important management decisions effecting the softwares 
Maanptainability. Decisions must be based on the size and 
complexity of software produced and what techniques are used 
by the organization performing the maintenance. This thesis 
has illustrated a small portion of available tynes. 

Institutions such as the Naval Postgraduate Schcol are 
in a position to improve the educetion of future computer 
mementists On the nature of software maintenance. This could 
be done by eStablishing computer science program libraries 
consisting of student develoved computer programs. Programs 
in these libraries would then be available for projects 
emphasizing program maintenance in additioneeto the 
traditional approach of emphasizin only program 
developrent. Crades based on how easily a student's trograr 
memuncerstood and correctiy modified by other students would 
provide an incertive for improving software maintenance 
Sreel ls. 

As a final thoueht, consider the findings of a study on 
software maintenance by Lientz and Swanson [73]. Their study 
“supports the proposition that an increase in the age of a 
system tends to lead to an increase in the level of effort 


in maintenance. This indicates that DoD must continually 


123 





meee ae difficult question: when is it more economical to 
iopose Of and redesign an Existing system thar to g0 on 


maintaining it? 





APPENDIX A - Program Maintenance Manual 


from: DOD STANDARD 7935.1S, Automated Data Systems 
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SECTION 1. GENERAL DESCRIPTION 


1.1 Purpose of the Program Maintenance Manual. This paragraph 
Shall describe the purpose of the MM (Program Maintenance Manual) 


in the following words or appropriate modifications thereto: 


The objective for writing this Program Maintenance 
Manual for (Project Name) (Project Number) is to provide 
the maintenance programmer personnel with the information 
necessary to effectively maintain the system. 


1.2 Project References. This paragraph shall provide a brief 
summary of the references applicable. to the history and develop- 
ment of the project. The general nature of the system (tactical, 
inventory control, war-gaming, management information, etc.) 
developed shall be specified. A brief description of this sys- 
tem shall include its purpose and uses. Also indicated shall 

be the project sponsor and user as well as the operating center (s) 
that will run the completed computer programs. A list of appli- 
cable documents shall be included. At least the following shall 
be specified, when applicable, by author or source, reference 
number, title and security classification: 


a. Users Manual. 

b. Computer Operation Manual. 

c. Other pertinent documentation on the project. 

Terms and Abbreviations. This paragraph shall provide a 
een Or include in an appendix any terms, definitions or 
acronyms unique to this document and subject to interpretation 


by the user of the document. This list will not include item 
names or data codes. 
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SECTION 2. SYSTEM DESCRIETION 





2.1 System Apolication. The purpose of the system and the 
functions it performs shall be explained. A particular appli- 
cation system, for example, might serve to control mission 
activities by accepting specific inputs (status reports, emer-~ 
gency conditions), extracting items of data, and deriving other 
items of data in order to produce both information ahout a 
Specific mission and information for summary reports. These 
functions shall be related to paragraphs 3.1, Specific Per- 
formance Requirements, and 3.2, System Functions, of the FD 
(Functional Description). 


2.2 security and Privacy. This paragraph shall describe the 
Classified components of the system, including inputs, outputs, 
data bases, and computer programs. It will also prescribe any 
privacy restrictions associated with the use of the data. 


2.3 General Descriotion. This paragraph will provide a com- 
prehensive description of the system, subsystem, jobs, etc. 
in terms of their overall functions. This description will 
by accompanied by a chart showing the interrelationships of 
the major components of the system. 


2.4 Program Description. The purpose of this paragraph is 

to supply details and characteristics of each program and sub- 
routine that would be of value to a maintenance programmer in 
understanding the program and its relationship to other pro- 
grams. (Special maintenance programs related to the specific 
system being documented will be discussed under paragraph 4.4, 
Special Maintenance Procedures.) This paragraph will initially 
contain a list of all nroarams to be discussed, followed by 

a marrative description of each program and its respective 
subroutines under separate paragraphs starting with 2.4.1 
through 2.4.n. Information to be included in the narrative 
description is represented by the following items: 


a. Identification - program title or tag, including 
a designation of the version number of the program, 


b. Functions - description of program functions and the 
method used in the program to accomplish the function. 


Input - description of the input. Descriptions used 
here must include all information pertinent to 
maintenance programming, including: 


(1) Data records used by the program during opera- 
€ion-. 


(2) Input data type and location(s) used by the 
program when its operation begins. 


Entry requirementS concerning the initiation 
of the program. 
2 
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Processing ~ description of the processing performec by 
the program, including: 


(1) Major operations - the major onerations of the 
program will be described. The description 
may reference chart(s) which may be included 
in an appendix. This chart will show the general 
logical flow of operations, such as rea? an input, 
access a data record, major decision, and print 
an output which would be represented by secments 
or subprograms within the program. Peference 
may be made to included charts that present each 
major operation in more detail. 


(2) Major branching conditions provided in the program. 


(3) Restrictions that have heen designed into the 
system with respect to the operation of this 
program, Or any limitations on the use of the 
program. 


(4) Exit requirements concerning termination of the 
Operation of the program. 


(S) Communications or linkage to the next logical 
program (operational, control). 


(6) Output data type and location(s) produced bv 
the program for use by related processing 
segments of the system. 


(7) Storage - Specify the amount and tyne of stor- 
age required to use the program and the broad 
parameters of the storage locations needed. 


Output - description of the outputs produced bv the 
program. While this description may reference out- 
put described in the Users Manual, any intermediate 
output, working files, etc. should be described for 
the benefit of the maintenance programrer. 


Interfaces - description of the interfaces to and 
from this program 


Tables and Items - provide details and characteristics 
of the tables and items within each program. Items 
not part of a table must be listed separately. Items 
contained within a table may be referenced from the 
table descriptions. If the data description of the 
program provides sufficient information, the program 
listing mav be referenced to provide some of the 
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necessary information. At least the following will 
be included for each table: 


(1) 
(2) 
(3) 
(4) 


(3) 


(6) 


(7) 


Table tag, label or symbolic name. 
Full name and purpose of the table. 
Other programs that use this table. 


Logical divisions within the table (internal 
table blocks or parts - not entries). 


Basic table structure (fixed or variable 
length, fixed or variable entry structure). 


Table layout (a graphic presentation should 

be used). Included in supporting description 
should be table control information, details 
of the structure of each type of entry, unique 
or Significant characteristics of the use of 
the table, and information about the names and 
locations of items within the table. 


Items - the term "item" refers to a specific 
category of detailed information that is coded 
for direct and immediate manipulation by a 
program. Used in this sense, the definition of 
an item is machine- and program-oriented rather 
than operationally oriented. Of primary impor- 
tance is an explanation of the use of each item. 
At least the following will be included for each 
item: 


(a) Item tag or label and full name. 
(b) Purpose of the item. 


(c) Item coding, depending upon the item type, 
such as integer, symbolic, status, etc. 


h. Unique Run Features - description of any unique features 
of the running of this orogram that are not included 
in the Computer Operation Manual. 
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ENVIRONMENT 





SECTION 3. 





3.1 Equipment Environment. This parayraph shall discuss the 
equipment configuration and its general characteristics as 
they apply to the system. ; 



















3.2 Support Software. This paragraph shall list the various 
Support software usec by the system and identify the version 
or release number under which the system was developed. 


3.3 Data Base. Information in this paragraph shall include 
a complete description of the nature and content of each data 
base used by the system. 


3.3.1 General Characteristics. Provide a general description 
a i en a e Al 
of the characteristics of the data base, including: 


a. Identification - name and mnemonic reference of the 
component (e.g., data base}. List the programs | 
utilizing the component and explain the use of the 

component in the system. 

t 


b. Permanency - note whether the component contains static 
data that a program can reference, but may not cCnange, 
or dynamic data that can be changed or updated during 
system operation. Indicate whether the change is 
periodic or random as a function of input data. 


c. Storage - specify the storage media for the data base 
(e.g., tape, disk, internal storage) and the amount 
of storage required. 


d. Restrictions - explain any limitations on the use of 
this component by the programs in the system. 


3.3.2 Organization and Detailed Descrintion. This paragraph 
will serve to define the internal structure of the data base. 

A layout will be shown and its composition, such as records 

and tables, will ke explained. If available, computer-generated 
or other listings of this detail information may be referenced 
or included, herein. The following items indicate the type of 
information desired: 










a. Layout - show the structure of the data base including 
record and items. 







b. Sections - note whether tt.. physical record is a 
logical record or one of several that constitute a 
logical record. Identify the record parts, such 
as header or control segments and the body of the 
record. 
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Fields - identify each field in the record structure 
and, if necessarv, explain its purpose. Include for 
each field the following items: 


(1) Tags/labels - indicate the tag or label assigned 
to reference each field. 


(2) Size - indicate the length and number of bits/ 
characters that make up each data field. 


(3) Range - indicate the range of acceptable values 
for the field entry. 


Expansion - note provisions, if any, for adding 
additional data fields to the record. 
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SECTION 4. PROGRAM MAINTENANCE PROCEDURES 

























Section 4 of the manual shall provide information on the specific 
procedures necessary for the programmer to maintain the programs 
that make up the system. 


4.1 Conventions. This paragraph will explain all rules, schemes, 
and conventions that have bdeen used within the system. Informa- 
tion of this nature could include the following items. 


to the tagging or labeling of programs, subroutines, 
records, data fields, storage areas, etc. 


b. Procedures and standards for charts, listings, seriali- 
zation of cards, abbreviations used in statements and 
remarks, and symbols appearing in charts and listings. 


a. Design of mnemonic identifiers and their application 


Com Thelacpropreiate Sctamcdarcs, fully identitied, may &¢ 
referenced in lieu of a detailed outline of conventions. 


dad. Standard data elements and related features. 


CS ESET 

requirements and grocedurcs necessary to check the verformance 
of a program section following its modification. Included may 
also be procedures for periodic verification of the program. 


4.2 Verification Procedures. This paragraph will include tnose 
SmuoeErrOr Condzttions. A deserioation of error conditions, not 
previously documented, may also be included. This descrintion 

shall include an explanation of the source of the error and 

recommencied methods to correct it. | 
Ava SpeCial Haintenance Procedures. This paragraph shall 
contain any soecial procedures rermvired which have not been 
delineated elsewhere in this section. Specific information 
that may be appropriate for presentation would include: 


a. Requirements, procedures, and verification which may 
be necessary to maintain the system input-output com- 
ponents, such as the data base. 







Requirements, procedures, and verification methods 
necessary to perform a Library Maintenance System 
run’. 











4.5 Special Maintenance Programs. This paragraph shall contain 
an inventory and descriztion of any special programs (such as 


file restoration, purging history files) used to maintain the system. 
These programs should be described in the same manner as those de- 
scribed in the paragraphs 2.3 and 2.4 of the i. 
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a. Inout-Outout Requirements - included in this paragraoh 
shall be the requirements concerning the ecuipment and 
materials needed to support the necessary maintenance tasks. 
Materials may, for example, include card decks for loading a 
maintenance program and the inputs which represent the changes 
to be made. When a support system is being used, this para- 
graph should reference the appropriate manual. 


b. Procedures ~ the procedures, vresented in a step-by- 
step manner, shall detail the method of preparing the inputs, 
such as structuring and sequencing of inputs. The operations 
or steps to be followed in setting up, running, and terminating 
the maintenance task on the equipment shall be given. 


4.6 Listings. This paragraph will contain or provide a reference to 
the location of the program listing. Comments appronriate to parti- 
cular instructions shall be made if necessary to understand and 
follow the listing. 


LS 








mp ENDIX 2 — Comdat System Program Description Group 





from: SECNAVINST 356@.1, Tactical Digital Systems 
Documentation Standards, 8 August 1974 


C. COMBAT SYSTEM PROGRAM DESCRIPTION GROUP 


1. PDO — PROGRAM DESCRIPTION DOCUMENT 
2. OBO — DATA BASE DESIGN 
3. PP — PROGRAM PACKAGE 
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PROGRAM DESCRIPTION 
DOCUMENT 


he 


1.0 Purpose. The Program Description document shall pro- 
vide a complete technical description of all digital processor, 
subprogram functions, structures, operation environments, 
operating constaints, data base organization, source and 
object code listing, and diagrammatic/narrative flows. Each 
subprogram or function shall be described in its own volume 
With referenced appendixes as digital processor printout 
listings. Each Program Description document shall be 

directly responsive to the Program Design Specification and 

to any appropriate software and/or program specification. 

The Program Description document shall be specifically 
Oriented to programming logic and programmer's language. The 
aim should be to describe and completely define the basic 
subprogram logic and program procedures for each application 
subprogram and for each system control subroutine. As a 
detailed compendium of the subprogram structure, the Program 
Description document will serve as the essential instrument 
for subsequent use by operational, maintenance, and contractor 
personnel diagnosing troubles, making adaption changes, 
designing and implementing modifications to the systen, 

and in introducing or adding new subprogram functions to 

the completed program. 


Figure 2-8. Program Description Documert (Page 1 of 16) 
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NOTE 


System subroutines are to be con- 
sidered in the same light as 
subprograms and require complete 
documentation as described for 
subprograms. However, in the 
interest of ease of handling, it 
may be convenient to group related 
subroutine descriptions into one 
volume of the Program Description 
document, e.g., executive program. 
This should be done only when 
separation of the subroutines 

into different volumes severely 
hinders understanding due to the 
interdependence of the subroutines. 


2.0 Requirements. The Program Description document shall 
be structured according to the format and description which 


is contained in figure 2-8 (pages 3 of 16 through 15 of 16) 
and are mandatory for use as a minimum. 


Figure 2-8. Program Description Document (Page 2 of 16) 
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SEGIION 12 SCOPE 


This section shall contain a summary description of the 
eurtictilre ana functioning Cf the subprogram in total. All 
major functions described in the Program Design Specification 
must be presented and briefly annotated. This section shall 
include, but not be limited to, the following paragraphs. 


tel rurpose. This paragraph shall describe the purpose, 
background, and intent of the Program Description document. 


ieeeeccope. [nis paragraph shall describe the scope and 
objectives that are intended by this document. Included 
herein shall be identification and subprogram tasks. 


1.2.1 Identification. This subparagraph shall contain the 
subprogram nomenclature, including its abbreviations and 
assigned designator. 


he2.2 Subprogram Tasks. This subparagraph shall consist of 
a detailed list with accompanying narrative of each function 


(e.g., the responsibilities) to be performed by the sub- 
program. 


SEGTION Z. APPLICA’ LE DOCUMENTS 


tiisesectrzon snall list sthose tactical publications, 
Instructions, specifications, standards, and other documents 
applicable to the preparation of the Program Description 
document. All cited documents shall list title, identifi- 
cation or serial number, exact date of issue, and publisher. 
i 


Figure 2-8. Program Description Document (Page 5 of 1€) 
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The list of applicable documents may also be appendix A, and 
referenced as such within this section. In aadarGa On. sit 
required, a glossary may be employed to list abbreviations 
and/or terms with definitions and shall be contained in 


appendix B. : 
SECTION 3. REQUIREMENTS 


This section shall contain a comprehensive description 
of the structure and functioning of the digital processor 
subprogram in total. All major functions described in sub- 
paragraph 1.2.2 "Subprogram Tasks", must be presented and 
fully amplified. This document shall comvletely describe 
all program logic. The minimum content shall consist of 
detailed information as follows. 


3.1 Subprogram Detailed Description. This paragraph shall 


describe the detailed design of each subprogram. It shall 
describe completely the processing capability of the sub- 
program. When combined with a program listing, flow chart, 
and data base description, this portion of the Program 
Description document shall fulfill the requirements of 
individuals whose responsibilities include program production, 
maintenance, and modification. This paragraph of the Program 
Description document shall con-ist of a textual development 
of the operations performed by the subprogram. It shall be 
organized by subprogram tags (mnemonic labels) and shall 
campletely describe each section of code as it appears in 
the subprogram listing. This, in essence, will describe 
the processing operations performed at each branch of the 
subprogram and the results obtained by following each branch. 
a 


Figure 2-8. Program Description Document (Page 6 of 1€) 
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Those subprogram tags that are common branch points from 
Several sections of code (or text) need only be described 


enee, and thereatter need only be referenced. 


During the discussion of subprogram segments, if common 
system subroutines are used, they shall be identified by 
inmerr fUnetlon and mnemonic label with a reference to the 


document where they are described in detail. 


The level of detail for this portion of the Program 
Description document amplifies the information provided in 
the subprogram flow diagrams described in section 4. Since 
the usual flow diagram presents a limited amount of infor- 
mation, flow diagrams are useful only as pictorial adjuncts 
to the required text description. The same subprogram tags 
specified in the text description shall be shown in the 
appropriate blocks of the related flow diagrams. 


3.2 Subprogram Flow Diagrams. A flow chart shall be included 


for each major procedure or subroutine that depicts detailed 
Operations performed by the subprogram. The flow chart shall 
specify all operations performed and include all equations 


used in mathematical computations. Comments in the program | 
Paimtoue listing shall be used in conjunction with this | 
Scetton, fo relate the text, flow charts, and code. Flow | 
diagrams shall show annotated logic flow among and between 

each program subdivision level down to, but not including, 

each compiler source statement, or to that source level 
containing comments if a compiler is not used. Source listing 
comments shall be brief narrative phrases, one for each com- 
Plvem seUnee starement; or, 1f a compiler is not used, then 


Pe) 


Figure 2-8. Program Description Document (Page 7 of 1€) 
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a comment for every logical switch or branch statement, and 
for an average of at least every 10 assembly level language 


statements. 


3.3 Subprogram Data Design. This paragraph shall contain a 


general summary description of the subprogram data base. The | 
overall format selected for this section shall be designed to 
facilitate the rapid retrieval of data base information. 
Throughout the Program Description document references shall 
be made to subroutines, constants and control-registers, input 
buffers and tables, output buffers and tables, priority/ 
interrupt tables, etc. Since many of these tables and 
Gentrol-repgisters Contain data that are referenced by more 
than one subprogram, it is sufficient that the detailed 
description of this common data base be a part of the Data 
Base Design document, which is used as a central source of 
reference for subprogram data. The following subparagraphs 
specify the level of detail that is required for this 


Program Description document section. 


Seo. fables. This Program Description document subparagraph 
shall contain the detailed description of each table used 
only in the subprogram data base. Each table shall be 
described individually, where the descriptions are presented 
according to the alphabetical ordering mnemonic table name.. 
The content of the subprogram table descriptions shall be as 
defined for describing common data base tables in the Data 
Base Design document. The minimum content of the subprogram 
table descriptions shall be: 

a. Table Name 

b. Purpose and Type 


Figure 2-8. Program Description Documert (Page & of 16) 


122 


¢c. Size and Indexing Procedure 


d= “Structuresand sit Layout. 


3.3.2 Variables. This Program Description document sub- 
Bamagnraphn siallscontain the Getailed description of each pro- 
gram included only in the subprogram data base. Each variable 
shall be described individually where the descriptions are 
presented according to the alphabetical ordering of the 
mnemonic names of the variables. The content of the subpro- 
gram variable descriptions shall be as defined for the Data 
Base Design document. The minimum content of this Program 
Description document subparagraph shall be: 

a. Constant Name 

b. Purpose 

c. Structure and Bit Layout. 


3.5.3 Flags. This Program Description document subparagraph 
shall contain the detailed description of each flag included 
only in the subprogram data base. Each flag shall be 
described individually, where the descriptions are presented 
according to the alphabetical ordering of the mnemonic names 
of the flags. The content of the subprogram flag descriptions 
shall be as defined for common flags in the Data Base Design 
document. The minimum content of this subparagraph shall be: 

a. Flag Name 

b. Purpose and Status 

Gammeorrlccure and Sit Layout. 


3.3.4 Indexes. This subparagraph shall contain the technical 
description of each index included only in the subprogram data 


base. Each index shall be described individually, where the 
5 
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descriptions are presented according to the alphabetical 
ordering of the mnemonic names of the indexes. The content of 
the subprogram index descriptions shall be as defined for 
common indexes in the Data Base Design document. The minimum 
content for this Program Description document subparagraph 
shall be: 

a. Index Name 

po hed eae 


3.5.5 Common Data Base Reference. This Program Description 
document subparagraph shall provide a complete list of all 
references to local and common data base items and the loca- 
tion of each reference. The list also provides a cross 
reference to the Data Base Design document which provides 
the technical description of the common data base items. 

If a Navy approved compiler is used, a cross reference 
obtained from the compiler may be substituted with written 
Navy approval by the procuring activity. 


3.4 Input/Output Formats. This Program Description document 


paragraph snall contain a brief description and graphic 
(sample) representation of each input and output message, 
card format, tape format, etc., processed by the subprogranm. 
ifechesrrogram Deseripe1on document volume concerns a common 
system subroutine, a detailed explanation and graphic repre- 
sentation of the input and output registers to and from the 
subroutine shall be provided. This shall include scaling and 
bit-position information (see figure 3-1). 


Figure 2-8. Program Description Document (Page 1¢ of 16) 
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31 DW 18 17 16 38 14 13 12 11:10 9 &8 7 6 $ 4 3 2 


Err PEER EEE SEL 


Test Target ~ Interpret os 5 non-tactical track 


ELEVATION ($5) A value expressing the elevation angle at which the rador Is 12 
to conduct its Sector Search, Minimum value is I degree. 
Manimum value is 85 degrees, MS8 =X, LSB = Y. 


al Sector 1] Blonking - Interpret os first vector in which the radar 
it blanked during Horizon Search Mode. 


82 Sector 2 Blanking - Interpret as second sector in -hich the 
redar is blanked during Horizon Search Mode. 


AT Alternate Air Target - Interpret os order to select alternate 
oir fusing for the appropriate missile type when the LS is 
asigned to the oppropriate MR. 


HR Horizon Seorch Request - Interpret os arder to alert the conwle 
asocicted with the copropriate MR te o Horizon Search 
Request. 

$0 Sector search Order = Interpret os rlace of propriate MR in 


Sector Search Mode. Assaciated with Elevation ($$). 


M2 Missile Rodor 2 - Interpret os a modifier. 

Mj Missile Radar 3 - Interpret os o modifier, 

GI Gun Rodor I - Interpret a1 o modifier, 

T TOT-1 = Interpret os o modifier to any data associated te indi- 


ate source of dota. 


T2 TOT=-2 - Interpret aso modifier to ony dato anoclated to Indi- 
cate wource of doto. 


TE Terminate Engagement ~ Interpret as Break Trock on ossaciated 
MR/GR and proceed to ony whrequent eAgogement require 
menn. Subject to legality checks, 


Fa Fire Again - Fire again on appropriate track. Subject to 
legality checks. 

GT Gun Torget < Interpret os a GR-I function ad route status to 
Gael, 

FT Faw Torget - Interpret os arenclated with fleld HR with appro- 
pricte MR. Does not apply te GR-}, 

RR Releave MR/GR - interpret os Break Track with no further 
engogement requiremenis ond retum MR/GR to Alr Ready 
mode . 


Figure 3-1 Sample Input/Output Word Format Description 
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3.5 Required System Library Subroutines. This Program 


Description document paragraph shall list, in alphabetical 
order, all system library subroutines used by the digital 
processor subprogram. It shall describe the area of the 


(EE 2 a 


functional description where use is made of the system 
library subroutine and the document number where the sub- 


mOouUtIne Gan be located. For example: 


System Subroutine Name Used Document Reference 
RIN (Arc Tangent) B.S Computer Subprogram : 


Design Document 


Volume 10 
SQS (Square Root) Se L Computer Subprogram 
Design Document 
ee Volume 10 


3.6 Conditions for Initiation. This Program Description 
document paragraph shall identify system conditions that must 
be met for this subprogram to be initiated for processing. 

For those subprograms that are always initiated for processing 
regardless of system conditions, the word UNCONDITIONAL shall i 
be shown. For those subprograms that are initiated due to one 
Or more unique conditions, each possible condition or set of 
conditions shall be described. If the conditions are based 
meee Setting Of Certaln items of information, each item, its? 
required value, and a definition (or reference) of that value 
shall be shown. | 


3.7 Subprogram Limitations. This Program Description docu- 


ment paragraph shall summarize any known or anticipated limi- 
Patrons Of the subprogram. A list of all restrictions and 
constraints that apply to the subprogram shall be provided 


including timing requirements, limitations of algorithms and 
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formulas used, design limits of input and output data, 
associated error condition sensing provided, and the error or 
reasonableness checks that are programmed into the various 


routines. 


peo nterroce Description. This Program Description document 


paragraph and an associated block diagram shall show the 
sequential and functional relationship of the subprogram with 
the other subprograms and system subroutines or executive. 
with which it interfaces. Figure 3-2 illustrates the block 
diagram showing the relationship between subprograms. 


SECTION 4. QUALITY ASSURANCE PROVISIONS 

This Program Description document section shall reference 
all applicable test plans and test procedures that have been 
used for verification of this digital processor subprogram. 
SECON S. PREPARATION FOR DELIVERY 

This section is not applicable to this decument. 


SECTION 6. NOTES 


This Program Description document section shall contain 
supplementary information. The information shall include 
but is not limited to: 

See eintormatioOn Of particular importance to the procuring 
agency in using these documents. 

b. Administrative and background information. 


Figure 2-8. Program Description Document (Page 12 of 16) 


Id 





dtysuolzelay aovz1z9quy 
q wes8o0idqns jo wei8etq Yyootg atduesg 7-¢ aaindty 


H 3) >3 
Wvt 90ud9Ns WV DOVdENS Wd DOVdBNS 
.¢) 
WY DOVdBNS 
2 8 Vv 
¥deNs 
Wv8D08dBNS Wv¥ DOwdeNns WvdDO 


“TTeD 10 adUdTITOI wessordqns aAedTpurl SMOITIY :920N 


10 


(Page 14 of 16) 


Figure 2-8. Program Description Document 


128 





Ge Ordering Instructions, tor technical data pertaining 


to the digital processor subprogram. 


This Program Description document section shall also 


list any documents necessary for use or understanding of this 
subprogram but not contained within the document. 


APPENDIXES 


The following appendixes may be included: 


a. AppendiaxeA. See section Z. 


boa A POCHOmxmDrmoece SeCCC1On 2. 


In addition, the Program Description document appendixes 
Shall include separate sections for information and data which 
are required for completeness in describing a variety of ! 
aspects of the structure and functioning of the subprogram. 
This data may be bound separately for convenience or may be 
published after the other sections have been issued in initial 
form. 


if 
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Gontent Check List 


ra 


Instructions with annotations, listings 

(1) Binary (tape, cards) 

(2) Machine, Assembly, Compile 

(3) Comments 

Procedures/ Subroutines 

(1) Procedure Diagrams - Logic 

(2) Procedure Data Design’ 

(3) Subroutine Flow Charts 

(4) Narrative, Index to Procedures, Subroutines 
Program Data Map 

(1) Common 

(2) Unique - Function 

(3) Index to Data 

Checkout (Validation) 

(1) Component Tests - [1/0 

(2) Subprogram Tests 

Gs) me ragcmesterecse Specification and, Description 
Technical Program Checkout Operation 

Gi eOnecK @POImnteEntry, Exit 

(2) Test Data Standards 

(3) Program Preset for Checkout 

Program Deviations from Technical Program Design 
(1) Subprograms 

CZ) SeEquipment Utility 

(3) Operator Actions 

(4) Allocations, with Deviations from Planned Budget 
(oye liming sRevisions ~ PrrOrity Deviations 
Addendum to Tech. Program Designs 

(1) System Program 

(2) Operator and Equipment Support Subprograms 


(3) Technical Subprograms. 
12 
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DATA BASE DESIGN 
DOCUMENT 


1.0 Purpose. The Data Base Design document shall provide a 
complete detailed description of all common data items 
necessary to carry out the functions of the digital processor 
program. Common data is that data required by two or more 
subprograms. Examples of common data include constants, 
indexes, flags, variables, and tables. The Data Rase Design 
document shall be based on the Program Performance Specifi- 
Cation. It shall be developed in accordance with the Program 
Design Specification and concurrently with the Subprogram 
Description document. The terminology employed in the Data 
Base Design document shall conform to the programming guide- 
lines in the Program Design Specification and the programming 
language employed for production of the digital processor 


program. 


2.0 Requirements. For convenience in describing the minimum 
essential content, figure 2-9 (pages 3 of 11 through 11 of 11) 
shows a normal format for presentation of the material. How- 
ever, the paragraph headings and numbers indicate the general 


Mature of the topic, and are mandatory for use as a minimum. 
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PARLE OP CONTENTS 


Page 

SECTION 1. INTRODUCTION 1 

ee Purpose 1 

ve Scope 1 
SECTION Z. APPLICABLE DOCUMENTS i 
SECTION 3. TABLES Z 
SECTION 4. VARIABLES $ 
SecllON 3. CONSTANTS 5 
SECTION 6. FLAGS 5 
SECTION. 7. INDEXES 6 
SECTION S. SUBPROGRAM REFERENCE (SET/USED) 6 
SECTION <9. NOLES, vi 
APPENDIXES i 

Ui oh 
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Layout Diagram 


LIST OP TABLES 


Table 
8-1 Sample Subprogram Reference 
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SECTION 1. INTRODUCTION. 


This section shall introduce the document and summarize 
the labeling conventions observed in the formation of mnemo- 
nics that identify data items for this program as defined in 
the Program Design Specification. 


poe Punpose, This paragraph shall describe the purpose and 
intent of the Data Base Design document. 


iiceeocope. This paragraph shall describe the scope and 
objectives that are intended by the document. 


SEGTION 2. APPLICABLE DOCUMENTS 


This section shall list all documents which apply to 
the preparation of this document and to the utilization of 
the digital processor system to which this document pertains. 
This section shall include, but not be limited to, references 
to the appropriate Program Perrormance Specification, Program 
Design Specification, and any additional documents that apply 
to the design or use of the Data Base Design document. All 
cited documents shall list title, identification or serial 
number, date of issue, and publisher. The list of applicable 
documents may also be appendix A and referenced as such within 
this section. Further, if required, a glossary may be employed 
to list‘abbreviations and/or terms with definitions and shall 
be contained in appendix B. 
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SEGCUION 3.) TABEES 





This section shall contain the detailed description of 
each table used in the common data base. Each table shall be 
described individually where the descriptions are presented 
according to the alphabetical ordering of the mnemonic name 
Of the table. The minimum content of this section shall be: 

a. Table Name. The title of the table with the assigned | 
mnemonic label in parenthesis, e.g., Common Track Table 
(EDIRK) . 

Dee clinpOccmaitm ny DCeE ie stable type (c.g), f1xed or 
variable length, table structure) and the explicit use of the 
cable. 

ccc manim nde xt MemenoGedure. sane number of items in 
the table and the number of digital processor words required 
Epapcachneadtem. lt shall also define, in precise terms, the 
Memmoduused tO Index through the various items of the table 
and any special conditions pertaining to the referencing of 


Ameiie Luded @atem . 


Following the description of the table, the subitems 
(fields) making up each item shall be defined. The minimum 
content of these descriptions shall be: 

a. Field Name. The title. of the field with the assigned 
mnemonic in parenthesis. 

Dace oscmand lypes An explici1e description of the use 
of the field that indicates its type (e.g., alphanumeric 


PMitLetet w tixea point, Or floating point). 
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G.- Size. “Une steeeo: the fleld in words or bits (if 


numeric) or number of characters (if alphabetic). 

d. Binary Point. This information shall be included 
for all numeric type fields except floating point, and shall 
Pidiucate the bit position of the binary point (scaling) of 
the variable. | 

e.  Rengerote a luesvanduingtial Condition. The minimum 
and maximum values that are valid for the field, and the 
Pitial condltronmor the field 1f itt 1S preset. For alpha- 
mumericG types the data code (e.g., ASCII, BCD) shall also 
Be woven. 

f. Static/Dynamic. The changeability nature of the 
field (e.g., unchanging value is static, changing field 
values are dynamic). 

Po cnlerunesand silt layout, 9A diagram for each digital 





processor word required by the field, as shown in figure 3-1. 
SECTION 4. VARIABLES 


This section shall contain the detailed description of 
each variable included in the common data base. Each variable 
shall be described individually where the descriptions are 
presented according to the alphabetical ordering of the 
mnemonic names of the variables. The minimum content of this 
paragraph shall be the following information and shall be in 
accordance with the requirements defined in section 3 of this 
document: 

a. Variable Name 

b. Purpose and Type 
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c. Size - number of bits and sign (1f numeric) or 
number of characters (if alphanumeric) 

d. Binary Point (not applicable to floating point 
numeric or alphanumeric types) 

e. Range of Values and Initial Condition 

Ew Static, Dynamic 


g. Structure and Bit Layout 


SECTION $5. CONSTANTS 


This section shall contain the detailed description of 
each constant included in the common data base. Each constant 
shall be described individually where the descriptions are 
presented according to the alphabetical ordering of the 
mnemonic names of the constants. The minimum content of this 
paragraph shall be the following information and shall be in 
accordance with the requirements defined for section 3 of this 
document: 

a. Constant Name 

b. Purpose 

Cine al Condrtion 

djewestructure and Bit Layout 


SECTION 6. FLAGS 
This section shall contain the detailed description of 


each flag included in the common data base. Each flag shall 
be described individually where the descriptions are presented 
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according to the alphabetical ordering of the mnemonic names 
of the flags. The minimum content of this paragraph shall be 
the following information and shall be in accordance with the 
requirements defined for section 3 of this document: 

a. Flag Name 

b Purpose 

Cee ind tral “Condition 

d Structure and Bit Layout 


SECTION 7. INDEXES 


This paragraph shall contain the detailed description 
of each index included in the common data base. Each index 
shall be described individually, where the descriptions are 
presented according to the alphabetical ordering of the mnemo- 
nic names of the index. The minimum content of this paragraph 
shall include the following information and shall be in 
accordance with the requirements defined for section 3 of this 
document: 

a. Index Name 


b. Purpose 
Se WlON@e meroubPROGRAM REFERENCE (SEI/USED) 


This section shall include a complete list of all common 
Gotaebasc teems With a cross reference which includes all 
referencing subprograms. The list shall be presented in the 
form of a matrix, where the rows are used for names of the 
items and the columns used for names of the subprograms. To 
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facilitate its use, the items and subprograms shall be listed 
alphabetically with S, U, or B utilized to indicate Set, 
Used, or Both (Set and Used), respectively. An example of a 
Subprogram reference matrix with Set/Used is shown in table 
8-1. 


SECTION =32, “NOTES 


This™section shall include a list of all subprograms by 
text name and mnemonic. The order of the list shall be in an 
alphabetical arrangement based upon the identifying subpro- 
gram mnemonic labels. Further information such as Subprogram 
Description document reference for each listed subprogram 
shall be included as required to facilitate the use of the 
Data Base Design document. 


APPENDIXES 


The following appendixes may be included: 


a Appendix A. See section 2Z. 


be Appendix B. See section 2. 


In addition, any information which is too bulky to be 
placed in the body of the document, such as further data 
description material or applicable support system listings 
from the assembler or compiler, (e.g., a common data or pro- 


gram data summary) shall be included as an appendix. 


zi 
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eal 
eal iTEM SUBPROG RAMS 


(TABLES) 
TABI(FLO!) - 
TABI(FLO2) 3 


TAB 1(FLO3) 8 


(VARIABLES) 
VRBLI ne 
VRBL2 ae 


VRBLO 8 


(CONSTANTS) 
CONST} U 


CONST2 U 


(FLAGS) 
FLGI ; 


FLG2 8 


(INDEXES) 


INDI -< 


IND2 oo 


~» e 





Figure 8-1 Sample Subprogram Reference List (Set/Used) 
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PROGRAM PACKAGE 
DOCUMENT 


Peeler pose.s tne Program Package document shall consist of 
all the program material items necessary for the procuring 
agency to produce, maintain, and update the digital processor 
Program. ‘These atems shall inelude, but not be limited to, 
the digital processor program source card deck listing, an 
error-free source/object listing produced by an assembly or 
compilation of the source decks, a complete cross- 

Beretence listing proauced by a compilation of the source 
decks, and any data which are necessary to cause programs 

to run properly (e.g. adaptation data, data file contents, 
set up data, program parameter values.) 


2.0 Requirements. The Program Package document shall be 
structured according to the format and description contained 
in figure 2-10 (pages Z of 19 through 10 of 10). However, 
the paragraph headings and numbers indicate the general 
nature of the topic and are mandatory for use as a minimun, 
with the exception of cross-reference and miscellaneous 
listings when not provided by the supporting compiler or 


assembler system. 


Figure 2-10. Program Package (Page 1 of 1@) 
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SECTION 1.” ~ENTRODUGTION = 


This section shall briefly define each of the required 
items in the digital processor program package. Within these 
definitions, general terminology is used to describe those 
items, and the requirements herein should not be construed 
to mean that each assembler or compiler system used for pro- 
gram generation must provide the explicit items called for 


in this section. 


1.1 Purpose. This paragraph shall describe the purpose, 
background, and intent of the Program Package document. 


ieaocope me Uasepaheagtapl small describe the scope and 
objective intended by this document. 


SEGlUCNe2. APPLICABLE DOCUMENTS 


This section shall list those tactical publications, 
instructions, specifications, standards, and other documents 
applicable to the preparation of the Program Package document. 
Memeartcaecqgcumentseshali list titie, wdentitication or serial 
number, exact date of issue, and publisher. The list of 
applicable documents may also be appendix A and referenced as 
such within this section. In addition, if required, a glos- 
Sary may be employed to list abbreviations and/or terms with 


definitions and shall be contained in appendix B. 
SECTION 3. SOURCE DIGITAL PROCESSOR PROGRAM 


This Program Package item shall be the complete source 
form of the digital processor program, suitable for assembly 
SEecompuiacion. § the physical form of the source program may 
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be card decks, or equivalent magnetic tapes. In either case 
the form of the source program shall be compatible with the 
production facility to which the program is delivered. For 
example, card readers may differ in their interpretation of 
the physical punches on a card for certain alphanumeric 
SyuNo ks evomcnl suis chescadsC,mlt.is the comtractonr's respon- 
SHbtlity COMcONEOrm to production facility formats. 


SECTION 4. OBJECT PROGRAM TAPE 


This Program Package item shall be the complete object 
form of the digital processor program, suitable for loading 
and execution in the operational digital processor. The 
object program shall be obtained from an assembly or compile 
of the source digital processor program containing no fatal 
errors and be completely free of patches. The physical form 
of the object program shall be on either magnetic or paper 
tape. In either instance, the object program tapes shall 
be compatible with the production facility to which the 
program is delivered. 


SEGMION 5. SOURGE PROGRAM LISTING 


This Program Package item shall be a listing of the 
sOurce digital processor program as delivered. The listing 
shall be an exact duplication of the delivered card decks 
Or magnetic tape. Each compiler source statement will be 
annotated with comments or if the source is assembly level, 
then a comment shall be listed for each assembly level line 
or function group of lines with not less than an average of 
One comment per five (S) statements. 

1s 
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SEGQION 6. SOURCE, OBJECT LISTING 


Tiise: oe rcamecacwa%coicem shall be a listing of the com- 
bined source statements and resulting object machine instruc- 
tions generated during an assembly or compile of the delivered 
Source programs. Figure 6-1 illustrates a typical source/ 
object listing. The source/object listing shall be free from 
fatal errors and be an exact presentation of the delivered 
source and object program. If the supporting compiler or 
assembler system does provide source/object listing, then the 


minimum requirement is the object listing. 
SECTION 7 GR OS5-REFERENGE LISTING 


This Program Package item shall be a listing showing a 
cross-reference table of each mnemonically labeled statement in 
the digital processor program and each statement in the digital 
processor program that references the labeled item. The table 
shall be ordered alphabetically according to the mnemonic labels 
and shall be generated as the result of an assembly or compile 
Pee ciemaelivenred SOULCe digital processor program. “Figure 7-1 
illustrates a cross-reference listing where the labels are 
alphabetically listed on the left side of the page and the 
address of each reference to the label is listed across the 


remainder of the page. 


SECTION 8. MISCELLANEOUS LISTINGS 


These Program Package items shall be included, as avail-. 
able, from the assembler or compiler system used in the 
digital processor program production. The Program Package 

S 
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items may include such listings as automatically generated 
subprogram flow charts, data base summary listings, and pro- 
gram summary data listings. Each of these items may be 
generated as a result of an assembly or compilation of the 
delivered source program. Figure 8-1 illustrates a procedure 
summary data base listing which describes the environment and 
parameters of each routine in the digital processor program. 


APPENDIXES 


The following appendixes may be included: 
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APPENDIX C — Standards and Conventions for Use of 
the CMS-2 Language 


Developed by: Tactical System Programming Support Branch, 
Wanine COnPamucdcuredl oyStem ouUDDOTU*ACtIVity, 
Camp Pendleton, California 92@55 


We round. while CMS-2 is not the most modern, state-of-the-art 
computer language in existence, it is nevertheless a powerful High Order 
Programmirg Language (HCL) which permits the development of well-designed, 
structured ccmputer programs. Wnen properly desizgned and coded, C4S-2 
programs can be readily maintained. The pursose of this document is to 
provide guidance for the design and coding (programming) of CMS-2 
prosrams. SECNAVINST 3560.1 (Tactical Disital Systems Decumentation 
Standards) and MIL-STD-1679 (NAVY) (weapon System Software Develooment), 
although excellent in many respects, provide little specific guidance with 
Gesard to the ¢ccmouter crogram itsel?t. The comcuter program listings is 
the single most important tool for software Pacrenenes: since guidance 
for computer programs is hishly language-dependent at the coding (or 
Pirscing) lével, cSis dccument srevides suidance in terms of the CMS-2 
language. These standards aust be complied with. Use of the words 
Pshali" and "must" mean Strict adherence is required. Section II defines 
terms which are used throughout the document. Section ITZ provides 
guidance on the desis and structuring of CMS-2 oregrams. Section IV 
gives specific guidance on the standards and conventions for ecdins CMS=2 


programs. 


It. Definition of Terma. The purpose of this section is to define seve 
eral programming terms in relation to specific CMS-2 constructs. This 
will serve to eliminate much of the semanticeal cenfusion which has pre- 


Valied. A acdule, as used is SECNAVINST 3&¢6C.1 and in this sterdard, 


salve 





shall ce a SYS-PROC be eollection of functionally related SYS-PRCC's. 
Where possible, one module as defined in the Program Design Specification 
(PDS) shall be mapped into one SYS-PROC in the C4S-2 program. However, 
where size becomes large, a collection of functionally related SYS-PRCC's 
may constitute a medule. aA routine, as used in SECNAVINST 3560.1 and in 
this standard, is a C4S-2 PROCEDURE or CMSe2 FUNCTION. All routines shall 
be PROCEDURES or FUNCTIONS; there shall be a one~tceone correspondence 
between them. The use of non-called, "in-line" routines is prohibited. aA 
prologue is defined as the lengthy set of ccmments found at the beginning 
of each PROCEDURE or FUNCTICN. Section IV.D srovides’ extensive guidance 


on prologues. 


aol 6 eq? 2 Penariyrea of CMSLD Dencwang, 
A. From PPS fo Srezram. The performance functional requirements 
described in the Program Perfermance Specification (2PS) small te zapped 
into program modules which are documented in the Program Desigz 
Specification (PDS). The modules of the PDS are then maoped into 
SYS=PRCC's (or legical zroups of SYS=@PRCC's) of the CMS-2 prosram. These 
SYS=-PROC's are further refined into individual PRCCZDURE's en FUNCTION's 
using the top-down method. The S¥SePRCC's and their subordinate 
PROCEDURES or rUNCTION's must then be documented in the Presran 
Description Document (PDD). It is important that the PDD contain the 
English name as well as the GS-2 mnemonic (or code name) of every 
SYS-PROC (medule), PRCCEDURE, and FUNCTION. Cnce this has been done, the 
computer frogram may te ecded. The entire process is characterized as a 


number of successive refinements; roving frem higher to lower (more 
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detailed) levels of abstraction; going from the seneral to the specific; 
progressing from functional requirements to the modules to the 
manifestation of the requirements in SYS-PRHCC’s, PROCEDURES and 
FUNCTION's. 

B. esi eiderations. The global data base requirements 
of the computer program should oe biae in ome SYS-DD. One SYS-DD should 
be used. However, if more than ome SYS-DD is used, it must be for a 
logical design consideraticn such as regional data pools (for large 
programs) er COMPCOL's for efficient compilation reasons. Under no 
circumstances will SYS-DD's be allowed to proliferate as desired by indi- 
Vidual programmers. Ccmputer programs having n SYS-DD's for n programmers 
is prohibited. In am analogous manner, each SYS=PRCC shall have only one 
“Loc-pD to describe its regional (local) data. The documentation or data 
base information shall be done in the ccmputer program listing. A Data 
Base Design document (D3D) is neither desired nor required. Guidance on 
how data base invormaticn is to be implemented in the pregrem listing is 
maven ion section Ly. 

C. Hiererchioel Structure. 

Bierarchical structure is important in a program. This struce- 
ture must be documented by means of a hierarcny diagram which skews the 
structural relationship between parts of the program. The 2DD shall show 
program structure within a module by means of a complete hierarchy 
diagram. The PDS shall show part of this structure by means of a 
hierarchy diagram which describes the sccgram down to the module 
(SYS-?20C) level diagram. Figure Be1 is an example hierarchy diasran 


which illustrates a number of desirable attributes of CMS-2 prograz 
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desian. There are five SYS=-PR0C's (EXEC, MANMACH, SIGPRCC, GECGAAPH, and 
COMMPROC) which comprise the major mcdules of the system. The hierarcni- 
cal structure of the program is shown by physical location om the chart 
and by the designation of levels. tn this example, the executive 
SYS=PROC, EXEC, is at the highest level of control and is at level Q. 
Only one module (SYS=-PROC), the executive, should be at level 0. Only one 
SYS-PRCC should provide overall control. All other aedules (applications 
modules) are subordinate and are at level 1 or below. where standard 
executives such as SDEX-7 or SDEX-20 are used, they will be at level Q. 
The SYS-PRO0C's shown at level 1 are the applications modules cf the C4S-2 
program. MANMACH provides the manemachine interface and ccnsists of the 
PROCEDURES MANMACHSP (which is the prime PROCEDURE), MCRTIN, MCRTCUT, 
MBUTTON, and MINDLAMP. Notice that, within each SY¥S-PRCC, the callings 
hierarchy is shown by indentation. For example, each prime PROCEDURE is 
Eouche Left of a1) cthers; and in SYS=?RGC GZOGRASH, fcr example, 
PHeoGooUnRs CANIPCL is to the right ef GRESECI. This shews that CARTDCL is 
subordinate to GRESECT. The following walkthrough is given fer further 
clarification: SYS=-PROC EXEC is at hierarchy level 0, SYS=PRCC GECGRAPH 
is at level 1, (PRIME) PROCEDURE GECGRAPHP is at level 2, PRCCEDURE 
GRESECT is at level 3, and PROCEDURE CARTPOL is at level 4. Ina large 
program there would be even more levels. SYS-=PRCC's (modules) are at 
levels 0 and 1; PRCCEDURES (and FUNCTION'’s) are at levels 2 cr nore. 
Although the CMS-2 language permits only two leveis of hierarchy frem an 
administrative or syntactical view, it is rossible to achieve many 
structural levels as dictated by the pregram design by the use of a 


calling hierarchy. 
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Common PROCEDURES fram the common SYS-PROC, COCMMPROC, are called from 
MANMACH and are thus shown in the hierarchy diagram where they are called 
even though they actually exist in SYS-PRCC COMMPROC. Using this conven- 
tion, a common PRCCEDURE may appear in several application SYS-=-PRCC’s 
where invoked. For example, CFILLEUF is shown in SYS=-PROC MANMACH and 
SYS=PROC SIGPROC since it is invoked from both places. The actual loca- 
Sich on GrLLLsUr danas. sotaer ccmmon PRCCEDURES is in SYS-PRCC COMMPROC, 
which serves to administratively group the common PROCSDUHES . Frem the 
total system viewpoint, CCMMPROC carn be considered to be part of the 
executive program, although functionally separate. Note that figure 2-1 
also shows the global data design, SYS-oD GLCBDATA, which contains all 
gicbal data items in ene place. 

There shall be no direct calls between SYS-PHOC’s. Control between 
SY¥S=PROC’s shall be passed through the executive acedule. PRCCEDURES 
within a SYS-PROC shall not call PROCEDURES in amother SYS-PROC except in 
the case of common PRCCEDURES which shall be grouped in once SYS~PHOC. 
PROCEDURES within the same SYS-PRCC shall call only those PROCEDURES which 
are subordinate, e.g., a PROCEDURE at level 3 shall call only PROCEDURES 


at level 4,5, 6... me 


is regramming Standarde and Conventiong 
A. Generali. The ecemputer program listing is the most important 
tool for the maintenance programmer. The importance of this Section 
cannot peberererenasi sed: The primary purcose of this Section is to 
maximize the maintainanility of CMS-2 program listings. Since cain- 


tainability is paramount, it is crucial to realize that clarity takes pre- 
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cedence over efficiency; readability takes precedence over writeability. 
The life-cyele of tactical computer crogram will see a large fraction of 
total system costs devoted to software maintenance. [It is important that 
CMS-2 programs be clear, concise, structured, well-designed, acdularized, 
and straightforward -= even at the expense of a few words of computer 
memory. | 
B. Program Oreanizoticr 

Figure Bed illustrates the physical organization of a well- 
designed CMS-2 pregram. As required by the compiler, the MAJCR EEADER 
comes first. When only one MAJOR ZEADER is required, all compile-time 
Sontrols shall te lecated in this MAJCR HEADER. Sowever, there 2re times 
when a program shculd be compiled several different ways to generate 
ebject code for different target computers. When this is required, MINOR 
HEADERS shall be used with each one containing different C-SwITCZss, 
MEANS, and ECUALS statements to generate different object pregrams. Then 


by use of the librarian, the desired object program may be generated 2 


ct 


compile time. The next program element after the various headers is the 
SYS-DD. Where sracticable, all giobal data items sheuld be declared in 
one SYS-DD. The restrictions of paragraph III.5 of this Enclosure apply. 
Next, the various SYS-rROC’s of the C4S-2 pregram appear, and, of course, 
there will normally be many zore than shown in Figure Be2. Each SYS-2R0C 
should contain a LOC-DD (if required) which is physically located at pee 
beginning of the SYS=PROC. After the LOC-DD, the various PRCCEDURES of 
the SY¥S-PROC will apoear, and each PRCCEDUnc shall contain LCC-INDEX'es 
(as required) at the physical beginning of the PRCCEDURE, immediately 


after the prologue. ‘snere prime PROCEDURES are used (and their use is 
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EXAMPLE SYSTEM 
MAJOR EEADER 


MINOR HEADER 1 


MINOR BEADER 2 


oe 


MINOR HEADER DCCUMENTATION 


® 
SYS=-DD- 


SYS=PRCC 1 
LOC-DD 


PROCEDURE 1A 
LOC-INDEX 


PROCEDURE 13 
LOC-INDEX 


SYS=-PROC 2 
LOC=DD 


PROCEDURE 2A 
LOC-INDEX 


PROCEDURE 23 
LOC-INDEX 


END=SYSTEM EXAMPLE 


#This MINOR HEADER contains the overall program description and crologue. 


Figure Be2 CMS-2 Program Physical Orsanization 
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encouraged), they shall be the first PROCEDURE in the SYS-PROC. The use 
of LOCREF ts preclude the necessity for forward referencing requirements 
at compile time is encouraged. The LOCREF operator permits PROCSDURES to 
be physically laid out im the listing in a topedewn order which 
corresponds to the program calling hierarecny. When C4S-2 FUNCTICNS are 
used, they should appear in a Iccation analogous to PROCEDURES. 
Cc. 34 and Beaders 

CSWITCHES are used to selectively vary object esde generated at 
cempile time. They are particularly useful when it is desirable to gener- 
ate different cbject prosrams for different (but similar) target eccmputer 
configurations. When this is done, the C-SWITCHE control statements that 
control the turning on and off of CSWITCHES will be located in a separate 
MINOR HEADER, and all cf these MINOR HEADERS will be included on the 
library tape. Of course, at compile time, those required will te selected 
by the librarian to generate cbject code for a desired target configura 
tion. Eowever, by placing all MINOR HEADERS on the library tape, all 
CeSWITCH settings will be available fcr inspection by maintenance pregrane 
mers. Each CSWITCH setting in each MINOR HEADER will be well decumented 
with a clear, detailed comment explaining the purcose of the switeh, the 
conditions when it should be used, and all unique aspects of the target 
Sgnticuration 14 is used for. Then, in the bedy of the program, CSWITCH 
brackets will be oighlizhted by use cf a blank line, a line of asterisks, 
a comment containing the CSWITCH title, another line of asterisks, and 


another blank line. For example: 
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FF SSRHSSSSSSSSSSASSSSSSSSSSSSSSSSSSSSSARSAAASSSSSSSSASSAFSSHSBARHT ¢ 1 


** CSWITCH TAOC IS USED TO GENERATE TARGET CODE FOR THE TACTICAL e 


** ATR OPERATICNS CENTER CONFIGURATION " 
MEPIS O OOO OOCOCLCrOCrrrorrecrrererrererrerrerrerrrrrrcrrerercre rs > mag 


CSWITCH TAOCC $ 


- « « « (program code) 


° & id ° 


88 SHSSSSSSSSSSSSSSSSSSHRSESFTSSASSSRASSSRSSLSHRSAAASRASSSSSSRESLRSRARBBRAH 87 


1’ END TACTICAL AIR OPERATIONS CENTER CONFIGURATICN CODE i 


FF SRSABRAPSSSASTSSSARSSSASSSAIFAADSSSSSSSSAASSSSSSSSLASESAAREAKAAARARSAS | 1 


END-CSwITCsS TACC $ 

Tae use cf nested CSWITCHES, while not prohibited, is discouraged. When 
MEANS and EQUALS are used for parameterizaticn and to achieve different 

target computer configurations, they will be included in separate MIYOR 

BEADERS as appropriate. They will be physically grouped tcgether within 
each header, not mixed with CSwiTCs controls and other compiver=coticas: 
Furthermore, every MEANS and EQUALS declaration will contain a comment 


which describes the purpose and use of the statement. For example: 


eee Tee LACE CONT ICURATION, Taz MaGyIRre DRIVE [5 CakLzD TO a 
Pcraivel 4. THIS EQUALS STATEMENT IS USED Di CONJUNCTION WITE ee 
Pomeowiica race, CUANGING THIS ONS STATEMENT WILL PERMIT HS '* 


BeeeveGnam TO INTERFACE WEIR MAG TAPE DRIVES GN OTSEA CZANNELS ae 
MTICHAN ECUALS 4 §$ ; 


Finally, headers should be legically SRST SESS So toate comsiter Fale he sek: 
CSWITCHES, MEANS statements, EQUAL statements, and — iteas are nae’ 
physically grouped together. | 
.D. & - 
Prologues, or carratives as they are sometimes called, are one 
of the mest important aspects of cemputer program documentaticn. Good. 


prologues are essential to the understandins of a pregram by maintenance 
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programmers. They are defined as the lengthy set of ccmments found at the 
beginning of each PROCZDURE in a well-documented program. Prologues are 
required at the beginning of every element of a CMS-2 program. Every 
prologue shall be clearly delimited frem executable code by use of lines 
of asterisks. <A prolegue is required at the beginning of the MAJOR 
HEADER, every MINCR HEADER, every SYS-0D, every SYS=-PRCC, every LCC-UD, 
every PROCEDURE, anc every FUNCTION in a C¥S-2 program. The larger and 
more complex the program element, the more extensive the prelegue snould 
be. Im additicn, there shall te a large MINOR HEADER wnich contains a 
prologue describing the purpose and function of the entire program located 
before the first SYS-DD (refer to Figure B-2). The program prologue shall 
describe the overall purpose and functioning of the program, the computer 
used for codpilation, the target computer (cr computers), the name of the 
chief programmer, the ccempany responsible Yor the program's development, 
the date the program was delivered to the goverrment, the nemenclature of 
the tactical system in which thre program executes, applicable references 
and standards (such as the Pregram Performance Specification and standards 
which deal with data links, fer example), and other pertinent data. In 
addition, each module of tne program will be listed, a orief description 
of each module will be given and the functional relaticnships of the 
modules will be Eriefly stated. The erder of execution, to include tke 
sequence in which the modules are invoked, will be explained in general 
terms. 

-The MAJOR EEADER and each MINOR EEACER shall contain a prologue. 
Wherever different headers are used to generate different object code, the 
prologue will describe the purrose of the header and specifically identify 


the target cemputer and equipment cenfizuratiocn. ; 
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The SYS-DD (or SYS-DD's) of the program snall contain a prologue 
which describes the global data design to include a descripticn of how the 
SYS-DD is organized. Specifically, MEANS and EQUALS declarations, TABLE 
declarations, and VRBL declarations shall be segregated and grouped 
according to type. This shall be explained in the SYS-DD prologue. As 
much as possible, the SYS-DD prologue shall pee ton as an index to the 
SYS-DD . Special naming conventions beyond those described in this stand- 
ard shall be explained in the prologue. 

Each SYS-PROC in the computer program shall have an extensive 
prologue. If a program module consists of more than one SYS-2RCC, then 
there will be a prologue at the medule level as well 2s one for each 
SYS=-PRCC within the module. This module level prolegue shall describe how 
the module functions, small be physically located at the top of the 
module, and shall list all SYS-PHOC's waich belong to the medule. wnen a 
module is equivalent to a SYS=-P8OC, the mocule prologue requirement is 
satisfied by the SYS-PRCC prologue. In either case, todule name, 


he 


ae | 


pregrammer(s), contractor, and delivery date shall be siven first. 
SY¥S-?RCC prologue shall contain an extensive, detailed deseription of the 
SIS-PHOC's purpose and function. The sequence of processing shall be 
described in chronolegical order to include the calling sequence of 
control. The hierarchical structure of the SYS=-PRCC shall te described, 
with the mame of every PRCCZDURE and FUNCTION siven. Finally, all inputs 
and outputs should be listed. The following example illustrates the 


structure of a good SYS-DD prolcsue: 
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MSMODOULE SYS-PROC $ 
COMMENT ## #@#@ @ eet Peo oH Ra RE HR ATER EUR HDLDmULDmULDLUCLELUCURURUAU 8 


MSMODULE - M-SERIES MESSAGE PROCESSING MODULE 

PROGRAMMERS: I.M. CODER, U. R. HACKER 

CONTRACTOR: SCETWARE UNLIMITED, INC. 

DELIVERY DATE: 30 MARCH 1980 

PURPOSE: TO PROVIDE TEE JOINT SERVICE INTERAGENCY MESSAGE PRCTCCCL 
REQUIRED CF THIS CCMPUTER PRCGRAM EY RESPONDING TO RECEIVED 
M=-SERIES MESSAGES AND TRANSMITTING APPROPRIATE M-SERIES MESSAGES 
AS REQUIRED BY THE TECENICAL INTERFACES DESIGN PLAN (TIDP). 

LEVEL: LEVEL CNE MCDULE. 

DETAILED DESCRIPTION: (This pertion of the prologue shall contain all of 

the items discussed in the paragraph above. In the case of large, cemplex 

modules, it may extend for five or six pases, or more. Processing sneuld 


be discussed in chronolegical order.) 


SUPERORDINATE SYS-PRCCS: 














(ete.) 
SUBORDINATE PRCCEDUORES: 

(ete.) 
FUNCTICNS: 

(etc.) 
INPUTS: 

(eta.) 
OUTPUTS: 

(ete.) 





#eeteteeaeeese eet eteeteeet eee tee eset eee ese etaee ats 


The prologue for each PRCCEDURE and FUNCTION shall be similar to 
‘that for each SYS-2RCC except that these prologues will deal with the pare 
ticular PROCEDURE or FUNCTION. 

Each LOC-DD and LCC-INDEX in the program shall have a brief pro- 
logue describing the purpose and organization (if necessary) of these data 
design elements. The use of asterisks and single quote marks to aighlignt 


key comments is encourased. 
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E. aia 15 

As specified in this standard, the Data Base Design (DBD) 
requirements of SECNAVINST 3560.1 and MIL-STD-1679 are to be met in the 
computer program listing. Consequently, it is very important that the 
data design elements of a CMS-2 pregram, the SYS-DD's, LCC-DD's, and 
LOC-INDEX's, contain the information found in the DBD. 

Where possible, all global data elements should be contained in 
one SYS-DD. The use of EXTREF and EXTDEF fcr variables and tables should 
be avoided. If these elements are global, they should be in the SYS-DD. 
If the SYS-DD becomes too large, in terms of CMS-2 symbol table capacity, 
then seme use of CCMPCCLS may be required. Local data elements btelorg in 
a LOC-DD, and sot in a SYS-DD. The SY¥S-DD should be organized to contain 
first the prolegue described in paragraph III.D, then all MEANS and EQUALS 
declarations (legically grouped), all VREL declarations (logically 
grouped), all TASLE (and array) declarations (logically grouped), and all 
PeSWITCH declarations. 

ALL MEANS and ECUALS declarations should be contained in the 
SYS-DD unless it is necessary to place scme of them in MINOR HEADERS so 
that the program may be compiled differently for different equipment 
configurations. The use of MEANS and SQUALS declarations in locations 
Gther than MINCR HEADERS or SYS-DD's is prohibited. The ve or .tne 
EXCHANGE primitive is ferbidden. Tre use of MEANS and EQUALS declarations 
to increase readability of the program is encouraged. Fer example, the 
statements 

TRUE MEANS 1 $ 


FALS<e MEANS 0 $ 


Tes 





increase the readability of the program. The use of MEANS and EQUALS 
Brim2aclves to reduce typing works, “such as 
PROC MEANS PROCEDURE $ 
is forbidden. The use of MEANS and EQUALS primitives to corrupt the CiS-2 
language such as, 
REPEAT MEANS GOTO $ 
is forbidden. The purpose of each MEANS or EQUALS declaration shall be 
documented with a meaningful comment as skewn in paragrapn IV C> 
VABL declarations shall contain seaningful comments which 
describe the purpose, initial value, range, and related data structures of 
Eoemvnibl.) Ine use Of short, cryptic comments "is, fordidden. Every VREL, 
mo matter how simple, must have the above attributes explained. dan exam- 
ple of a good VREL declaration is: 
"¢ MSGCPTR IS TSE MESSAGE QUEUE FOINTER WHICH ALWAYS POINTS TO ue 
UTS TEE GASTeMeosAG. WHECA HaS ELeN INSERTeD INTO TABLE MSGQUEUE. *'* 
CT ET Senior LALIZeD TO ZERO GwEEN TEE MESSAGE QUEUE IS EMPTY ut 
"' AND ITS RANGE IS FACM 0 TO 25 (WEEN TES MESSAGE QUEUE IS net 
*' FULL). IF IT IS £VER GREATER THAN 25, AN ERROR CCNDITION es 
"* (QUEUE OVERFLOW) WILL RESULT, AND TES QUEUE WILL BE FLUSHED is 
P Nba oGer (ARE OE Ll cou0. Jy 
VREL MSGQPTR I 16 U0 POS 
TABLE declarations are similar to VRSBL declarations when it 
comes to documentation requirements. Because TASLES can be very cemplex 
data structures, they aust be explained in detail. Each TABLE, SUG-TABLE, 
LIKE-TABLE, and FIELD will be described as to purpose, initial value, 


range, and related data structures, if any. The following example illus- 


trates these ccencepts: 
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COMMENT 
TABLE ACCOUNTS IS USED TO STORE INFORMATION CN 400 BANK ACCOUNTS. 
EACH ITEM (OR ACCCUNT) CONTAINS AN ACCOUNT NAME (FIELD ACCTNAME) WHICH 
CAN CONTAIN UP TO 40 ASC11 CHARACTERS, AN ACCOUNT NUMBER (FIELD 
ACCTNR) WHICH CAN NANCE FRCM ZERO TO $999, A BALANCE WHICH CAN RANGE 
FROM -9999.99 DOLLARS TO +9999.99 DOLLARS, AND AN ACTIVE/NON-ACTIVE 
FLAG (BOOLEAN FIELD ACTIVE) WHICH WHEN THUE (=1) MEANS ACTIVE AND 
NON-ACTIVE WHEN FALSE (20). AT PROGRAM INITIALIZATION TIME, THE 
ENbits TASLS —S SLOUSBED (SET 10 ZEROES). INDICES (CR POINTERS) 
RELATED TO THIS TAELE ARE VRSLS LASTACCT, NEXTACCT, AND NEWACCT. 3 


TABLE ACCOUNTS VY DENSE ugg $ 
FIELD ACCTNAME 82 20 
FIELD ACCTNR I 14 U 
FIELD BALANCE A 22S 7 
FIELD ACTIVE 3 

END-TABLE ACCOUNTS 

Note that the FIELD declarations are indented two columns in from the 


wm tr & t? 


Pape G@eclaration to show “subordination. dlso, that H, I, A, and Band 
20, 14% and 22 are vertically aligned. where possible, TABLES and YRBLS 
shall be declared in alphabetical order. 

Local data items found in LOC-DD's and LOC-LNDEX's shall be 
grouped and cecmmented as snown above for SY¥S-DD's. The importance of 
placing data elements which are required by only one SYS-PROC into the 
LOC-DD cannot be overemphasized. This practice premotes information nid- 
ing and permits different programmers to work on different SYS-PR0C's 
without concerning themselves with the names and details of other 
SYS=PROC's. 

P-SWITCH's shall be declared in the SYS-DD if the PRCCEDURE's 
-used are global in scope. Pe-SWITCd's shalt de declared in a LOC-DD if the 
PROCEDURE's used are of local scope. The’ declaration of a 2?-SWITC2 
outside a SYS-DD or LCC-DD is forbidden. They shall be well-ccmmented as 


shown in the example below: 
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COMMENT 
BASED ON THE VALUE CF GLOBAL VARIABLE TRIGINDX (RANGE: 0-5), TRIS 
PeSWITCH WILL CALL THE APPROPRIATE PRCCEDURE WHICH WILL RETURN TSE 
VALUE FOR CNB CF Tae SEX TRiGOnGMETAIC FUNCTIONS: SINE, COSINE, 
TANGENT: COTANGENT, COSSCANT, OH SECANT. THE RNPUT ANGLS MUST EE AN 
ANGLE EETWEEN PLUS OR MINUS 260 DEGREES, AN A-TYPE VREL (a 24 S 14) 
WITH FRACTIONAL ACCURACY TO ONE PAZT IN 16,384. OUTPUT TRIGANS 
RETURNS AN ARITEMETIC VALUE IY THE RANGE PLUS OR MINUS 262,144 WITH 
FRACTIONAL ACCURACY TO ONE PART TY 8,192 (A 32 5 13). CERTAIN 
TRIGONOMETRIC FUNCTIONS, SUCH AS TANGENT (90 DEGREES) HAVE INFINITE 


VALQE. I THESE CASES, # VALUE OF 252,144 IS RETURNED. $ 
P-SWITCH TRIGFUNC INPUT ANGLE CUTPUT TRIGANS $ 
SINE We CASE 0 mr $ 
COSINE i CASE 1 tt é 
TANGENT is CASE 2 tt 8 
COTANGNT ee CASE 3 ne 3 
COSECANT ve CASE 4 ike $ 
5 oe 3 


SECANT ee CaS 
END=SWITCH TRIGFUNC $ : 


The use of the P=-SWITCE operator _ Gultipath branching is preferred over 
the use of tne FOR cperator in most cases. Hcewever, there are instances 
when Che FOR operator is preferable; for example, when two or more values 
cause branching to the same procedure or when the range of values is aot 
sequential. In the latter case, the FOR statement avoids the need for 
dummy precedures. in other ccmputer lanzuages, rQR is used for iterative 
leoping. Only in C¥4S-2 is it used for multipath brenchinzs. Since 
P-SWITCH declarations are physically separated from their invocaticn, a 
meaningful ccmoment at the point of invocation shall be nrovided for 
elarity. 
F. sizeof Slements. 

There is no limit (other than these imposed by the compiler) to 
the size of a SYS-DD or LOC-DD. PROCEDURE's and FUNCTIONS's are linited 
to 100 lines of C4S-2 source code, exclusive of comments. This is an 


absolute limit which may be exceeded only upon pricr aporoval by the 
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goverment on a case-by-case basis. Where PROCEDURE's and rUNCTICN's 
contain direct code, they are limited to 50 lines of code, exclusive of 
comments. The average size of all PROCEDURE’s shall be 50 Lines. 
Exceptions to these size restrictions are mot permitted. Pregrams with 
overly large PROCSDURE's indicate poor design and a lack of partitioning 
the pregram into functionally independent parts of manageable, naintain- 
able size. The use of "ineline routines” is expressly forbidden. 

Every procedure shall have one and only ome entry point. This 
is am absolute restriction. Every procedure should have only one RETURN 
er exit point, although this is not am absolute recuirement. 

G. Naming Conventions. 

In the naming of pregram elements such SYS=-PRCC's, VREL's, 
TABLE's, and PROCEDURE's, the CMS-2 language leaves much to be oe Beat inc - 
Names are limited to eight characters and the be aca vie character as not 
permitted. This inhibits the readability of names. Hcwever, within the 
constraints of the compiler, much can te dome to enhance readability and 
marntainasilicy, which is the subject of this section. 

Every module, or SYS-PROC, in'a C1S-2 program shall have a 
unique prerix consisting of one or two characters. If less than 26 med- 
ules ccmprise the program, then cne letter will suffice as the module 
‘prefix. If more than 26 modules are used, or if the program desisner 
‘ Believes that it will enhance maintainability, then two characters gsnall 
be used.. These two cnaracters shall be two letters or a letter followed 
by a number. Examples of cne-letter prefixes are UG for UTILMCD, a utili- 
ties module and M for MMICMOD, 2 aane-machine interface module. Examples of 


twoeletter prefixes are M3 for M3MCDULE and IO for IOMCDULE. 
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Once a prefix has been established for each SYS-PROC (module), 
then every subordinate element of that module shall use the module prefix 
as the first one or two characters of every name. Fer example, ICMODULE 
might have as subordinates PRCCEDURE's IOMTAPE (a magnetic tape handler), 
IOTTY (the teletype bandler), amd ICCRT (the computer-CRT interface). 
Every PROCEDURE, VRBL, FUNCTION, TABLE, etc. of a zodule snall contain its 
prefix as an identifying mark. Common (global) data elements are not 
subject to these restrictions, but will be named with a prefix starting 
Wicd one Wetcer C. 

All names within a CMS-2 program shall be descriptive. They 
shall attempt to describe the item they represent. Names such as 
IOBUFFER, USINE, and MSGFLAG nave inherent meaning and are easier fer a2 
maintenance programmer to remember while tracing threush a program. Names 
such as A, &, N, or BX are meaningless, and their use is forbidden. Rela-~ 
ted data elements should have related names which show their interrela- 
tionship. For example, a TABLE called IOBUrTrER might logically have an 
index or pcinter which is called ICBUFPTR. Applying the above rules and 
common sense will increase the maintainability of a C4S-2 pregram. 

BR. hole halam 

Without good commenting, even a well-designed program can be 
extremely difficult to maintain. The use of neaningful ccmments to 
increase the understandability of a prozsram cannot be overempnasized. 
Additionally, it ismalnest impossible ts overcecaement. if is better te 
overcomment than to undercorment. This section deals with in-line ccn- 
ments which serve to explain ard supplement source code rather than 


PROCEDURE and module prologues which are discussed in section D. There 
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are three kinds of ccoments: stand alone, which are on a separate line 
from any source code; terminating, which follows source code on the same 
line; and embedded, which are embedded within a source code line. More 
will be said about these three types later. For consistency, all stand 
alons comments shall precede the code they explain. 
Comments should expiain, amplify, and supplement source code 
rather than echo the code. For example the statement and comment 
SET NTO N +1 '' INCREMENT NN '' 

dees nothing to explain why N is being incremented. It is also an example 
of a terminating comment. Terminating comments are prohibited, except 
with direct code and to amplify data declarations. A better method of 
commenting would be: 

'* A MESSAGE BAS JUST BEEN INSERTED IN MSGCUSUE. MIICREMENT - 

P evscerin sO teal Lf POINTS: To = ECCabven Wears Thee ven) MSG 

UT OMAY EE SISERTED. Je 

SET MSGQPTR TO MSGQPTR +1 $ 
Another example of an a Nhat AE comment is: 

of? ee MESSAGE CUeUr Cale CULY HOLD 25 MSGS. TeUs,, © MSCQETR oS eg oe 

"' 25 CVERFLOW BAS RESULTID-~fLUSE THE MESSAGE QUEUE. * '! 7 ae 

Bay SEIS GT 25 THEN FLUSEQ $ ais 
In CiS-2, there should be, cn the average, no less than one line of 
commenting for every two lises of source code. In direct code, there 
should be, on the average, no less than one comment for avery tinecor 
direct code. These averases pertain to amplifying comments, exclusive of 
prologue comments. These averages are minimum requirements. The use of 
more ccmments is encouraged. 


The rollowing example illustrates good terminating comments for direct 


code: 
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L R3,CQPTR ~CQPTR POINTS TO ITEMS IN 

LE R4,6 oA CIRCULAR QUEUE OF SIZE 7 
~AND SHOULD RANGE FRCM O TO 6 
-IN VALUE - SO INCREMENT IT OR 
»ZERO IT DEPENDING ON ITS VALUE 
-COMPARED TO 6 


CR R3, R4 ~IfF CQPTR LESS THAN 6 THEN 

JL INCRMT ~GO TO INCREMENT 

EL RS, 0 -LUsbwoll sGernt eles chne 

o RaqeGGern -AND SAVE IT 

J BYPASS -BYPASS INCREMENT CCDE 
INCRMT. IROR & ~SEl COPTR=COPTR+1 

Shs, Garrn ~AND SAVE IT 
BYPASS. . CONTINUE 





The above comments do not echo the cede, they explain it. The comments, 
in effect, translate the assembly language into high level code. Contrast 


this with the following ccoments that merely echo the code: 


L 23, COPTR ~PUT CQOPTR IN REG 3 
LK R4, 6 -PUT 6 IN REG 4 
CR R3, R4 COMPARE REGS 3 AND 4 


These comments are worse than nome at all, for they insult the maintenance 
programmer by insinuating that he does not mow the assemdly language 
gastruction set. 

In addition to echoing the code, there are several cther pnit- 
falls that seme ccmmenters fall into. One of these is the "80 colunn 
mentality" where the programter crowds terminating comments into the same 
line as the code at the expense of abbreviating ‘the ccmment into an incon 
prehensible line of garble. For example the statement and ccnoment 
SET MSGQFTR TO MSGQPTR+1 '* INCR MSGQPTR PT NXT MSG '' $ 
would have been better as, 


** INCREMENT MSGCFTR TO POINT TO THE NEXT MESSAGE IN TEE QUEUE 7 
SeT MSGQPTR TO MSGQPTR +1 $ 
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Another common pitfall is the embedded comment. For example the statement 
IF '? THE MSG CPTR '' MSGQPTR GT 25 
an wolle, CF Tae QUEUE ** THEN 
Pm’ ELOSH THE QUEUE "' FLUSEQ S$ 
embeds so many comments into the code, it is difficult to distinguish 
between the code and the comments. Embedded comments 2re prohibited. The 
preferred aethod is to place comments on separate lines, and, where 
appropriate, separate them frem the ccde by indenting, using blank lines, 
and blocking comments with asterisks. 
i } L2var 

Good physical layout is defined as that property of a ccmputer 
program listing which makes it capable of being read and understood by a 
programmer not familiar with the program. Good physical layout implies 
ease of Maen esndine and zgocd readibility. Good readability may de 
achieved by a variety of techniques, some of which are separation of 
logical elements of code, separation of comments and ecde, blocking (by 
using lines of asterisks) lensthy comments or prologues, the approoriate 
use of blank lines, logical indentation, and the linings up of BEGIN-cND 
and IF-<£LSE cairs. | 

Separation of logical elements and the use of blank lines zo 
hand in hand. The practice of beginning PRCCEDURES on a new page serves 
{oO separate these logical elements and premote readability. The use of 
blank lines to senarate prolczgues and lengthy comments frem executable 
code also promotes readability. Prologues and lengthy ccmments should be 
bexed by asterisks to make them stand out and be separated frem the code. 
Blank lines snould be used freely to prevent crowding and to separate 


logical entities. 
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Indentation is a key part of physical layout. Indentation is 
defined as the physical indenting of logically subordinate and nested pro- 
gram constructs. <A truly structured program is structured in two ways. 
Persc, it is. $tructuréd witS Seeeea to the flow of control of the program. 
pecooa, it is physically structured by ttre’ use of indentation. 

Indentation shall be used so that program logical pairs are lined up and 
stand out. Every BEGIN shall be pnysically indented to line up with its 
corresponding END. The nested level or the BEGIN-END block shall se 
denoted by a number in a terminating comment. The following example 
illustrates the gocd use of indentation to achieve readability. 


Beary '* t '' $ 





[epepeeee = TEEN 
BEGIN ‘'2'' $ 








ieee ee TEEN 
BEGIN 3°" 3 


END ''3't $ 
ELSE 
BeGrn (4 '* 5 


END Teer $ 
END peat $ 
END oy te at 
In the above example, it is clear which EEGIN belongs with which END. The 
practice of "hiding™ BEGIN's as follows 


293 THEN EEGIN $ 





is prohibited. 
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CMS-2 has two drawbacks which make indenting difficult. First, 
the code must begin in column 11 or later; Columns 1-10 are not availaole 
for indenting. Second, the fact (in C4S-2Y at least) that side-by-side 
object code begins in column 28 cemplicates the problem. If tke 
programmer indents too much, the source C4S-2 code gets mixed up with tke 
generated object code. The situation calls for case-by-case judgements on 
the part of the programmer. As a rule, two columms per indentation level 
is preferred when there are eight or less levels of indentation. thes 
more than eizht levels of indentation or nesting ceccur, the programmer 
should use one column of indentaticn per level to avoid mixing the source 
and object code. 

A final note on readability: all PROCEDURES shall begin at the top of a 
mew page by use of the pase eject function. (SYS-PROC's and SYS-DD's are 
placed at the top of the pase automatically by the compiler.) 

J. Direct Codes 

Direct code should te used enly to achieve input or output, werk 
around compiler problems, er to eptinize frequently executed code. 
Optimization will be done cnly after testing of the fully loaded running 
System proves that optimization is required. The latter reason for using 
direct code is permitted only wren prior approval is given by the 
cognizant government agency. This will be done on 2 case-dy-case basis. 
Direct code shall Se used to work around erpiten iecolens only when it is 
not possible to work around them in high-level code. Whenever direct code 
is used, it skall te clearly separated frem the high level code by the use 
of blank lines, lines of asterisks, and a prolcgue, similar to the pro- 


logue required at the beginning of each procedure. This proelesue shall 
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describe the reason for tne section of direct code. Within the section of 
direct code, the use of ccmments is important (see Section H on commenting 
@irect code). 
K. Jaye 

The use of complex IF clauses can cause logical problems with 
the flow of control of a CMS<-2 program. IF clauses should be ginple, such 
as 

IF IOFLAG EQ 10 THEN ... 
Complex IF clauses are difficult to understand and lead ee flaws. 
The use of more than one AND er ome OR per IF clause is discouraged. 
Where complex If statements are used, they shall be generously commented. 


The use of the CCMP operator is forbidden. 
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17. (U) OBJECTIVE AND APPROACH: Reduce the life cycle cost of Naval software 
by conducting a critical experiment to assess the value of software 
engineering (SE) innovations to assure that a) technology base funds are spent 
only on potentially useful techniques, and b) software acquisition managers 
are made aware of the value of these techniques. In the experiment, an 
existing flight software package for the A-7 aircraft is being redesigned in 
accordance with new SE principles and the efficiency, real-time performance 
and flexibility of the new software will be compared with the performance of 
software produced by more conventional methods. 


18, (U) PLANS. FY 80: Initiate redevelopment of A7 Onboard Flight Program 
(OF?) in accordance with the following software engineering techniques: 
Information Hiding Modules, Abstract Interfaces, Cooperating Sequential 
"Processes, Process Synchronization Primitives, Uses Hierarchy, Resource 
Monitor Modules, Formal Specifications, Disciplined Programming and Progreéna 
Verification. , 

FY80: Continue redevelopment and begin to assess advantages and coscs of 
these techniques. FY81 milestones: Complete design documentation, Dec 79; 
complete implementation of a kernel of software to perform a selected subset 
of functions, June 80. 


19. (U) PROGRESS AND ACCOMPLISHMENTS. This project was initiated with NRL 
Technology Base funding; a Software Requirements document was produced under 
that project. The document has been reviewed by NWC personnel for accuracy™ 
and sufficiency. It describes the principal interfaces between the software 
and the other system components and all the functions to be perforned by the 
software. Thia document will serve as a reference for the remainder of Che 
project, and is being used by NWC for other purposes. A paper has been 
published about the techniques developed to document software requirements. 
The major software modules and patterns of interaction have been identified 
and described. 
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